물때 API 응답이 왔다고 안전 판단에 써도 될까요
2026.10.19

소개
수신 성공 다음에 남은 질문이 있었습니다
물때 자료를 연결하는 과정에서 제가 구분해야 했던 것은 응답이 왔는지와 그 응답을 어떤 판단에 써도 되는지였습니다. 앞선 화면 통합과 지도·기상 연결을 거쳐 국립해양조사원 조석예보 API까지 연결했지만, 숫자가 도착했다고 바로 간조 달력이나 출조 추천을 만들지는 않았습니다. 시간과 높이의 의미를 확인하는 일이 남아 있었기 때문입니다.
이 글은 2026년 10월 18일까지의 v15·v16 기록과 당시 공식 문서 대조 결과를 바탕으로 작성했습니다. 저는 원자료 수신과 운영 안전을 별도 상태로 남긴 과정을 소개하려고 합니다. 이후 현재 상태를 재검증한 글은 아니며, 실제 조회 응답 원문이나 인증 자료를 공개하는 글도 아닙니다.
설명용 일러스트, 실제 앱 화면 아님: 물때 응답을 받았어도 그 의미를 안전하게 해석한 것은 아니다.
진행 방법
짧은 계속 요청이 해석의 승인까지 뜻하지는 않았습니다
당시 제가 Aside에 보낸 실제 요청은 다음과 같습니다.
실제 요청 원문
연결진행해
계속 진행이 요청은 연결 작업을 이어 가려는 것이었습니다. 하지만 실제 조회 성공, 화면의 자료 해석, 운영과 안전의 승인은 서로 다른 일입니다. 제가 공개용으로 정리한 작업의 요청 요약은 아래와 같습니다. 다음 블록은 원문의 직접 인용이 아닙니다.
요청 요약
공식 조석 API의 신청과 연결을 진행하고 실제 응답을 확인해 주세요.
문서와 실제 수신의 차이를 기록하고 확인되지 않은 뜻은 추정하지 마세요.
시간대와 높이 기준면이 미확인이면 원자료 표시와 안전 판단을 분리해 주세요.처음에는 해당 API의 인증 연결이 없어 실조회가 막혀 있었습니다. Aside는 공식 로그인 링크와 화면을 제공했고, 사용자 직접 로그인 이후 무료 개발계정 신청과 승인 확인을 진행했습니다. 이 글에서 중요한 것은 계정의 상세가 아니라 승인 종류입니다. 개발 자료를 호출할 수 있게 됐다는 승인이지 앱 운영이나 현장 안전에 대한 승인이 아니었습니다.
공식 문서끼리도 같은 모양은 아니었습니다
Aside는 정확한 Swagger 1.0.0과 공식 HWP 1.0을 대조했습니다. HWP에는 2025년 12월 12일의 배포 정보가 있었습니다. 문서를 읽는 단계에서부터 응답 구조의 차이가 발견됐습니다. JSON 설명은 최상위에 header와 body를 두지만 XML 예제에는 response라는 바깥 틀이 있었고, 항목이 하나일 때 객체인지 여러 항목의 배열인지와 페이지 정보의 위치도 문서 표현이 달랐습니다.
성공코드 역시 단순하지 않았습니다. HWP 표에는 0, 예제에는 00이 있었고 Swagger는 결과코드의 의미를 충분히 규정하지 않았습니다. 네트워크 요청의 HTTP 200을 응답 안의 결과코드 200이라고 간주해서도 안 됐습니다. 저는 공식 문서를 읽었으니 형식을 다 안다고 말하는 대신, 어느 문서에서 무엇을 확인했는지 남기는 방식이 필요하다고 봤습니다.
기존 잠정 어댑터가 모든 공식 구조를 처리한다고 주장할 수 없다는 점도 기록했습니다. 어댑터는 공급자의 응답을 앱이 읽을 수 있는 형태로 바꾸는 부분입니다. Aside는 별도 v15에서 문서에 근거한 대체 구조만 한정적으로 처리하도록 보완했습니다. 아무 위치에서든 원하는 값을 찾아내는 임의 탐색 대신, 모호한 구조나 잘린 페이지 정보, 잘못된 값은 거절하는 방향이었습니다.
단위가 있어도 기준까지 확인된 것은 아니었습니다
조위값에 cm라는 단위는 확인됐습니다. 그러나 높이를 어느 기준면에서 잰 값인지에 대한 정의는 확인한 문서에서 찾지 못했습니다. 시각 항목에도 예시 문자열은 있었지만 KST인지 UTC인지 같은 시간대 정의를 찾지 못했습니다. 이는 제공기관 어디에도 정의가 없다는 단정이 아니라, 당시 확인한 공개 문서 범위에서는 찾지 못했다는 뜻입니다.
앱이 응답을 받은 시각을 한국 시간으로 기록하는 일은 가능했습니다. 하지만 그것이 제공자 예보 시각의 시간대를 확인해 주지는 않습니다. 마찬가지로 cm를 화면에 표시할 수 있다는 사실이 그 값을 현장 수심으로 해석할 근거가 되지도 않습니다. 저는 수치의 형식이 맞는 것과 수치의 의미를 이해하는 것을 나눠야 했습니다.
이 때문에 조석 요청 날짜를 기상과 달력 날짜에 자동으로 맞추지 않았습니다. 후속 v16에서는 제공자 요청일을 별도로 고르게 했습니다. 서로 다른 시간 기준일 수 있는 값을 한 날짜 선택에 묶으면, 화면은 편해 보여도 확인하지 않은 대응 관계를 사용자에게 전달할 수 있기 때문입니다.

설명용 일러스트, 실제 앱 화면 아님: 기준면과 시간의 연결이 확인되지 않으면 해석을 멈춘다.
실제 수신은 확인하고 해석 상태는 남겨 뒀습니다
v15에서는 인천 공개 관측소의 해당 요청일 예보를 실제로 한 번 요청해 고저조 예보 4건을 수신했습니다. 이 글에서는 개별 시각과 높이 원문을 옮기지 않고 수신 여부와 건수만 설명하겠습니다. 근거 문서에 정리된 결과를 확인했으며, 실제 HTTP 응답 원문 로그나 키 자료는 열지 않았습니다.
수신 상태는 RECEIVED_UNVERIFIED, 즉 받았지만 검증되지 않은 자료로 남겼습니다. 시간대와 높이 기준면의 검증값은 false였고 safetyAssessment는 null을 유지했습니다. null은 위험하지 않다는 판정이 아니라 안전 평가가 없다는 뜻입니다. 이 구분을 화면의 원자료 참고표와 안내에도 반영했습니다.
인증키를 연결하는 일도 조회 자체와 분리했습니다. 당시 구현은 서버 메모리에만 연결하고 파일이나 실행묶음에 포함하지 않는 방식이었습니다. 서버를 종료하면 다시 연결해야 했습니다. 이 설명은 당시 구현·검증 기록의 범위이며, 현재 키 보관 상태를 다시 검사한 결과는 아닙니다.
v16 재수신 뒤에도 미확인은 사라지지 않았습니다
v16에서도 실제 조석 요청 1회로 4건을 수신했습니다. 같은 회차에서 기상도 실제 조회했지만, 기상 시각과 조석 시각을 같은 해석으로 묶지 않았습니다. 수신 상태를 쉬운 한국어로 안내하고 원자료 표와 모델 예보를 구별했습니다. 자료를 다시 받았다고 시간대나 기준면에 대한 공식 정의가 생긴 것은 아니었습니다.
파일과 실행 도구의 자동시험은 모의 응답으로 형식 호환과 거절 조건을 확인했고, 브라우저의 실제 요청은 별도 수신 근거로 남겼습니다. v15 자동시험은 2,024개, v16은 2,118개 통과였습니다. 이 수치들은 선언한 프로그램 동작의 검사 결과입니다. 수천 개 시험을 통과해도 문서에서 미확인인 의미를 대신 확정해 주지는 않았습니다.
결과와 배운 점
성공 상태를 하나로 합치지 않았습니다
저는 이 작업의 결과를 신청 승인, 실제 응답 수신, 자료 의미 확인, 운영 사용 판단으로 나눠 보게 됐습니다. 개발계정 승인은 호출 준비의 근거였고, 실제 4건 수신은 연결의 근거였습니다. 시간대와 기준면은 여전히 미확인이었으므로 달력의 간조 표시, 높이 안전필터, 출조나 입수 추천에는 적용하지 않았습니다.
안전 평가를 비워 둔 것은 연결 실패를 감추려는 선택이 아니었습니다. 오히려 연결은 성공했지만 아직 해석할 근거가 부족하다는 상태를 드러내는 방식이었습니다. 숫자와 함께 미확인 항목도 드러나는 결과로 남겼습니다. 앱이 답하지 못하는 질문을 사람에게 정확히 넘기는 것도 필요한 기능이었습니다.

설명용 일러스트, 실제 앱 화면 아님: 데이터 수신과 안전 판단 사이에는 멈춤이 필요하다.
다음 판단에는 다른 근거가 필요했습니다
남은 일은 제공기관의 정확한 시간대와 높이 기준면 확인이었습니다. 실제 현장 안전과 운영 검증은 별도 과제였고, 실기기와 영속 저장, 전체 배포도 완료하지 않았습니다. 저는 더 자주 호출하거나 원자료를 더 많이 모으는 것이 이 공백을 자동으로 채우지는 않는다고 정리했습니다. 필요한 것은 수신 횟수의 증가보다 뜻을 확인할 근거였습니다.
AI에게 연결을 맡기면서 사람이 해야 했던 판단은 어디까지 자동으로 해석할지를 정하는 일이었습니다. Aside는 문서 차이를 대조하고 한정된 호환을 구현하고 실제 수신을 확인했습니다. 저는 그 결과를 운영 안전으로 확대하지 않는 경계를 유지했습니다. 2026년 10월 18일 기록의 결론은 물때 연결 완료와 안전 판단 완료가 같은 문장이 될 수 없다는 것이었습니다.
도움 받은 글 (옵션)
v15·v16 작업 기록, README·검증결과·쉽게 연결하기 문서와 당시 공식조석 확인결과를 참고했습니다. 공식 Swagger와 HWP 대조 사실은 보관된 확인 문서에 근거하며 이번 작성 중 외부 원문을 새로 열지는 않았습니다.
로그인하고 댓글을 남겨 주세요
진태님, 안녕하세요! 신청 승인, 실제 수신, 자료 의미 확인, 운영 사용 판단을 네 단계로 나눠 보신 구성이 명확해요.
safetyAssessment를 null로 두고 "위험하지 않다는 판정이 아니라 평가가 없다는 뜻"으로 구분하신 부분이 특히 좋았습니다. 수신한 고저조 4건은 RECEIVED_UNVERIFIED로 남기고, 시간대와 높이 기준면이 미확인이라 달력의 간조 표시나 출조 추천에는 쓰지 않았다는 판단도 안전과 직결되는 자료라 설득력이 있어요. HTTP 200과 응답 안의 결과코드를 구분하신 점도 놓치기 쉬운 부분이었어요.
다음 글에서 기준면 확인 결과가 나오면 꼭 보고 싶어요. 오 이 부분 진짜 재밌어요 👀

v15와 v16에서 각각 실제 요청 한 번으로 예보 4건을 받았는데도 안전 평가는 비워두셨네요. 앞선 물때 기록에서 시간대와 높이 기준면을 확인 조건으로 잡으셨던 진태님이, 이번에는 실제 수신 뒤에도 그 조건을 그대로 유지하셨습니다. 이제는 연결이 막혀서 판단을 못 하는 상태가 아니라, 연결은 됐지만 해석 근거가 모자라 판단을 멈춘 상태라는 차이가 드러나요. 재수신이 미확인을 지워주지는 않는다는 설명도 이 변화 안에서 설득력이 있습니다.
공식 문서끼리 응답의 바깥 구조와 항목·페이지 표현이 달랐다는 대조가 그 과정을 구체적으로 보여줍니다. 문서에 근거한 구조만 한정해 처리하고 모호한 값은 거절하도록 한 보완은 형식 호환의 진전이지, 예보 시각이나 높이의 뜻까지 확인한 결과는 아니었네요. 앱이 수신 시각을 한국 시간으로 기록할 수 있어도 제공자 예보의 시간대는 별도로 확인해야 한다는 구분이, v16에서 조석 요청일을 기상·달력 날짜와 따로 고르게 한 화면 결정으로 이어졌고요. 자동시험 통과 수가 늘어난 사실도 이 빈칸을 대신 채우지 않으셨습니다. 확인한 문서 범위에서 정의를 찾지 못했다는 표현 역시 제공기관 어디에도 정의가 없다는 단정과 달라서, 무엇을 근거로 어디까지 말할 수 있는지 정확히 읽게 돼요.
실제 수신을 확인한 성과와 간조 표시·높이 안전필터·출조 추천을 보류한 결정을 같은 무게로 적어주셨습니다. 원자료 참고표에 미확인 상태를 함께 남겨주신 덕분에, 화면에 숫자가 있다는 사실과 그 숫자로 결정을 내려도 된다는 허락 사이에 무엇이 필요한지 보입니다. 연결 이후에 남은 해석의 책임까지 드러내주신 기록이라 고맙습니다.