낚시어때의 지수는 공공 데이터로 만든다. 물때는 국립해양조사원이, 바람·기온·강수와 특보는 기상청이 낸다. 데이터를 직접 만들 수는 없다. 앱의 품질은 이 API들을 얼마나 잘 붙이느냐에 달려 있었다. 두 달 동안 세 곳을 붙이며 배운 것을 적는다.
왜 이 세 곳인가
후보는 두 경로로 모았다. 공공데이터포털에서 물때·날씨·바다로 검색해 나온 API, 그리고 Claude 리서치로 추천받은 API다. 그중 실제로 붙인 곳은 세 곳이다.
- 공공데이터포털의 기상청 서비스: 단기예보(기온·강수·바람), 기상특보
- 공공데이터포털의 국립해양조사원 서비스: 조석예보(만조·간조), 조위관측소·해양관측부이 실측, 바다낚시지수, 바다여행지수
- 기상청 API허브: 해구별 파랑예보(연안 파고·파주기), 지상관측 일자료. 포털과는 다른 플랫폼이다. 신청 절차도, 한도를 보는 곳도, 시간대 규약도 다르다.
이 밖에 해양수산부 낚시어선 신고정보, 한국농어촌공사 저수지 수위, 카카오 주소 검색, 브이월드 지도를 쓴다.
유료 날씨 API는 따져 보지 않았다. 유료를 검토한 것은 지도뿐이었고, 무료인 브이월드로 갔다.
국립수산과학원: API가 없어 기준값만 인용했다
수온은 낚시에서 가장 중요한 값 중 하나다. 국립수산과학원은 고수온·냉수대 특보를 내고 수온 예측도 발표한다. 그런데 예측을 받아 올 오픈 API가 없었다. 공개된 API는 관측값만 준다. 8월에 확인하고 9월 13일에 한 번 더 확인했지만 그대로였다. 거기서 조사를 끝냈다. 냉수대 예측은 웹의 이미지로만 나온다.
그래서 국립수산과학원 자료는 기준값으로만 쓴다. 고수온 예비주의보(25℃)와 주의보(28℃) 기준을 수온 지수 곡선에 넣었다. 그 온도에 가까워질수록 지수가 빠르게 떨어진다. 실제 수온은 국립해양조사원의 관측과 예측 모델에서 가져온다.
키 발급과 활용신청
첫 활용신청은 7월 23일이었다. 개발계정은 신청하자마자 승인됐다. 포털의 개발계정은 서비스마다 하루 10,000건까지 부를 수 있다.
문제는 개발 중에 생겼다. 물때표를 빠르게 보여 주려고 관측소 41곳의 400일치 조석을 미리 받아 두기로 했다. 이것만 약 16,400건이다. 개발계정 한도로는 안 됐다. 8월 7일에 운영계정 전환을 신청했다. 신청한 서비스는 11개였다. 서비스마다 어느 화면에 쓰는지 설명하고, 출처를 표기한 화면 캡처를 붙였다.
기상청은 다음 날 승인됐다. 국립해양조사원은 소식이 없었다. 8월 11일에 문의하니 기관에서 검토할 시간이 더 필요하다는 답이 왔다. 승인은 8월 13일에 났다. 보완 요청이나 반려는 없었다. 이유는 포털의 서비스 페이지에 적혀 있었다. 기상청 단기예보는 운영단계도 자동승인이고, 국립해양조사원 조석예보는 운영단계가 심의승인이다.
기다리는 동안 미리 받기는 한도에 걸렸다. 8월 9일, 만 건 가까이 받았을 때 「일일 서비스 요청제한 횟수 초과」가 돌아왔다. 같은 날 다른 국립해양조사원 서비스는 잘 불렸다. 한도가 풀렸다고 보고 다시 돌렸다가 바로 또 막혔다. 한도는 계정이 아니라 서비스마다 따로 센다. 결국 며칠에 나눠 받았다. 끝난 관측소는 건너뛰고 이어 받게 만들었다.
승인이 곧 사용 가능은 아니었다. 기상특보는 활용신청이 승인된 뒤에도 한동안 403이 나다가 저절로 풀렸다. 운영계정으로 바뀌어도 인증키는 그대로였다. 코드는 고칠 것이 없었다.
기상청 API허브는 따로 신청했다. 9월 5일에 필요한 API를 신청했고 그날 안에 모두 열렸다. API허브는 API 단위로 신청한다. 같은 지상관측이라도 시간자료와 일자료를 따로 신청해야 했다. 신청하지 않은 API는 403, 없는 주소는 404가 돌아온다. 하루 한도는 응답에 나오지 않고 마이페이지에서만 보인다. 검증하는 동안 쓴 양은 한도의 1.4%였다.
문서와 실제가 다른 곳
API 문서를 읽고 코드를 짠 것은 대부분 Claude Code였다. 그래서 어느 문서가 헷갈렸는지는 내가 답하기 어렵다. 대신 어디를 여러 번 고쳤는지는 기록에 남아 있다. 고친 횟수가 가장 많았던 곳은 기상특보와 바다낚시지수였다. 바다낚시지수는 붙이고 7주 뒤에 결함 다섯 개를 한 번에 찾았다. 한 번에 받는 행이 모자라 지점 49곳 중 9곳이 빠져 있었다. 캐시에 날짜가 없어 자정이 지나도 전날 목록이 남았다.
| 어디 | 예상 | 실제 |
|---|---|---|
| 국립해양조사원 조석예보 | 가이드 예제처럼 한 겹 감싼 응답 | JSON은 감싸는 층 없이 온다. 두 형태를 다 받게 했다 |
| 조석예보의 만조·간조 구분값 | 문자열 | 관측소에 따라 숫자로도 온다. 7월 27일 내 폰에서 물때가 전부 「간조」로 나와 알았다 |
| 국립해양조사원 조위 시계열 | 지원하지 않는 관측소는 오류 | HTTP 200에 본문 코드로 알린다. 우리 관측소 56곳 중 8곳 |
| API허브 해구 파랑예보 | 오류는 오류 상태 코드 | HTTP 200에 본문 문구로 알린다 |
| API허브 시각 | 한 가지 규약 | 해구 파랑은 UTC, 지상관측은 KST |
| 결측값 | 한 가지 표기 | 해구 파랑은 −999, 지상관측은 −9 |
| 단기예보의 파고 항목 | 파고 예보 | 바다 격자 전용이라 육상 격자에서는 0이다. 9월 13일에는 5개 지점에서 48시간 내내 0.5로 고정돼 왔고, 이 값이 「실측」으로 표시되고 있었다. 이 항목을 버리고 해구 파랑예보로 바꿨다 |
| 지상관측 시간자료 | 요청한 기간만큼 | 31일을 넘기면 오류 없이 잘린다 |
| 지상관측 강수 | 1시간 강수 | 4 |
| 해구 파주기 | 실측과 비슷 | 부이 실측보다 약 5% 길게 나온다 |
| API허브 응답 형식 | 구분자로 나뉜 표 | EUC-KR 공백 정렬 텍스트. 행마다 필드 수가 다르다 |
| 기상특보 「자료 없음」 코드 | 한 가지 | 기능에 따라 “03”과 “3” |
세 가지는 따로 적어 둔다.
시간대. API허브는 API마다 시간대 규약이 다르다. 해구 파랑예보는 UTC로만 요청을 받고, 지상관측은 KST다. 시간대를 잘못 맞춰도 오류는 나지 않는다. 9시간 어긋난 값이 조용히 들어온다. 테스트에서도 한 번 걸렸다. 컴퓨터의 시간대를 따르는 함수 때문에 테스트 서버에서 날짜가 하루 밀렸다. 시각 계산은 KST 유틸 하나로 모으고, 테스트는 UTC로 고정해 돌린다.
결측값. 값이 없을 때 쓰는 숫자가 API마다 다르다. 해구 파랑예보는 −999, 지상관측은 −9다. −999만 걸러 내면 지상관측의 −9가 「기온 영하 9도」로 그대로 통과한다. 검증 중에 실제로 한 해구에서 −999를 받았다. 결측을 거르는 기준은 API마다 따로 둬야 한다.
오류도 200. 상태 코드는 성공인데 내용은 오류인 응답이 두 곳에서 나왔다. 조위 시계열은 지원하지 않는 관측소에도 200을 주고 본문 코드로 알린다. 해구 파랑예보는 오류 문구를 200 본문에 담아 보낸다. 게다가 소해구 자료가 아직 올라오지 않았을 때도 「해구번호를 확인하라」고 나온다. 요청이 틀린 것으로 오해하기 쉽다. 그래서 성공 여부는 상태 코드가 아니라 본문을 보고 판단한다. 조위 시계열은 결과 코드를, 해구 파랑예보는 데이터가 시작되는 표시가 있는지를 본다.
호출은 서버에서만, 캐시로 한도 안에서
공공 API는 전부 서버에서 부른다. 앱은 우리 서버만 부른다. 외부 API 키가 앱에 들어가지 않고, 공공 API 호출이 사용자 수만큼 늘지 않는다.
캐시는 두 겹이다. 서버 메모리와 데이터베이스에 두고, 캐시 키에 KST 날짜를 넣는다. 빈 결과는 캐시하지 않는다. 실패한 결과는 아주 짧게만 기억한다. 공공 API가 느려질 때 같은 요청을 계속 보내지 않으면서, 살아나면 금방 반영하기 위해서다.
갱신은 두 방식을 섞는다. 요청이 왔을 때 캐시가 비어 있으면 부르고, 전국 공용 데이터는 예약 작업이 미리 채운다. 전국 목록 하나를 여러 지점이 나눠 쓰니 호출 수는 지점 수와 상관없다.
앱에도 캐시가 있다. 같은 요청은 한 번만 보내고, 마지막으로 성공한 값을 기기에 남겨 둔다.
운영 트래픽이 한도에 걸린 적은 없다. 한도에 걸린 것은 앞에서 말한 미리 받기 작업뿐이었다.
응답이 없을 때
공공 API는 가끔 멈춘다. 이것을 전제로 짰다.
- 보조 데이터가 실패해도 지수 계산은 멈추지 않는다. 그 부분만 빈 채로 간다.
- 파고는 단계적으로 내려간다. 부이 실측 → 해구 파랑예보 → 바람으로 추정. 추정값에는 「추정」 표시를 붙여 실측처럼 보이지 않게 한다.
- 새 값을 받지 못하면 마지막으로 받은 값을 보여 주고, 왜 그런지 화면에 알린다.
처음부터 이렇게 되지는 않았다. 장애가 세 번 있었다.
8월 16~17일. 서버에서 국립해양조사원으로 가는 연결만 실패했다. 기상청은 멀쩡했다. 그런데 바다여행지수를 부르는 코드 한 곳에서 예외가 새어 나왔다. 지수 API 전체가 500을 냈고, 13시간 넘게 이어졌다. 보조 데이터 하나가 핵심 기능을 통째로 멈춘 것이다. 그 호출이 실패해도 넘어가게 고쳤다. 연결이 왜 끊겼는지는 끝내 확정하지 못했다.
8월 22일. 같은 증상이 다시 났다. 이번에는 앱이 「공공데이터포털 응답이 없어 일부 값을 추정치로 대신 보여 준다」는 안내를 띄우고 버텼다. 저절로 회복됐다. 원인은 이번에도 확정하지 못했다.
9월 6일. 공공데이터포털 쪽 장애였다. 오전에는 일부 서비스가 504를 냈고, 한낮부터는 포털의 API 주소가 간헐적으로 아예 응답하지 않았다. 같은 시각 포털 웹사이트는 열렸다. 이때 결함이 하나 더 드러났다. 실패하면 안내를 띄워야 할 홈 카드가 로딩 표시에서 멈춰 버렸다. 평소에는 응답이 빨라 보이지 않던 결함이었다. 고치면서 결론을 하나 남겼다. 배치 수집, 서버 캐시, 실패하면 직전 값 유지는 선택이 아니라 전제다.
약관과 출처 표기
포털의 기상청·국립해양조사원 서비스는 공공누리 제1유형이다. 출처만 밝히면 상업적으로 쓸 수 있고 바꿔 쓸 수도 있다. 각 서비스 페이지의 「이용허락범위」에 적혀 있다. 이용료는 없다.
앱은 기관명을 병기해 출처를 밝힌다. 지수 근거 화면에는 「국립해양조사원 바다낚시지수」처럼 기관과 자료 이름을 적고, 값마다 실측·예보·추정 표시를 붙인다. 특보 화면에는 「기상청 발표 ○시 기준」을 적는다. 설정의 데이터 출처 화면에도 기상청과 국립해양조사원 항목을 넣었다. 1.0.0부터 들어가 있다.
앱 화면의 데이터 표기 원칙은 1.0.0 출시의 「정직한 데이터」 절에 있다.
가져다 쓸 것
- 쓸 API를 먼저 정확히 고르고, 운영계정을 일찍 신청한다. 나는 개발계정만 받아 두고 개발하다가, 미리 받아 둘 자료가 생기자 한도에 막혀 운영으로 바꿨다. 심의승인 서비스는 며칠 더 걸린다.
- 포털 한도는 서비스마다 따로 센다. 한 서비스가 불린다고 다른 서비스 한도가 풀린 것이 아니다.
- 상태 코드를 믿지 않는다. 200이어도 본문에서 성공 여부를 확인한다.
- API마다 시간대와 결측값을 표로 적어 두고 시작한다.
- 공공 API는 멈춘다. 서버에서 부르고, 캐시하고, 실패하면 직전 값을 보여 준다. 보조 데이터 하나가 핵심 기능을 끌고 내려가지 않게 호출마다 실패를 가둔다.
- 대량으로 미리 받을 때는 끝난 곳을 건너뛰고 이어 받게 만든다. 한도에 막혀도 다음 날 그대로 이어진다.
출처
이 글은 2026-10-19 기준으로 헥사허브가 직접 겪은 일을 적었습니다.