FOR DEVELOPERS
웹과 앱에서 함께 쓰는
물때정보 API
공식 예보를 서버에서 받아 같은 형식으로 전달합니다. 서비스키는 서버에만 보관하고, 앱에는 노출하지 않습니다.
GET /v1/stations
등록된 국립해양조사원 조석예보 지점 목록을 반환합니다.
curl https://api.물때정보.com/v1/stations
GET /v1/tides
station과 date(YYYY-MM-DD)가 필요합니다.
curl "https://api.물때정보.com/v1/tides?station=busan&date=2026-10-19"
실제 조석예보를 제공합니다. 현재 배포 주소에서 /v1/tides를 호출할 수 있으며 api.물때정보.com은 도메인 연결 후 사용할 예정입니다. 인증키 미설정은 503, 원본 서비스 오류는 502를 반환합니다.
날씨·해양 정보 API
아래 경로는 모두 station, date를 받습니다. 성공 응답은 meta, station, data로 구성됩니다. 시간은 +09:00, 미제공 수치는 null입니다.
GET /v1/weather· 초단기실황과 선택일 시간별 예보. 단기예보 범위 밖은 안내와 빈 시간 목록을 반환합니다.GET /v1/sun· 일출·일몰·월출·월몰. 제공기관이 반환한 기준 지역을 함께 전달합니다.GET /v1/observations· 선택일의 마지막 수위·수온·바람 관측. 미래 날짜는 404입니다.GET /v1/buoy· 연결된 주변 부이의 선택일 마지막 관측. 위치·직선거리·파고·파주기를 포함합니다.GET /v1/tide-curve· 확인된 주변 해역의 10분 간격 예측 조위. 만조·간조 지점과 다릅니다.
일부 지역은 연결된 부이 또는 확인된 TideBED 해역 지점이 없어 404를 반환합니다. 미설정 키는 503, 제공기관 오류는 502입니다. 자료별 오류가 물때표 조회를 중단하지 않습니다. 공개 GET API이며 모든 경로에서 CORS를 지원합니다.
추가할 수 있는 공식 데이터
각 서비스의 활용신청 후 서버 환경변수에 인증키를 보관합니다. 날씨·출몰시각·관측 수위·부이 파고·주변 해역 조위 그래프를 사이트에 연결했습니다.
| 환경변수 | 데이터 · 공식 신청 페이지 |
|---|---|
| KMA_SERVICE_KEY | 기상청 단기예보 기온·강수확률·바람 |
| KASI_SERVICE_KEY | 한국천문연구원 출몰시각 일출·일몰·월출·월몰 |
| KHOA_TIDEBED_SERVICE_KEY | 국립해양조사원 TideBED 좌표별 1분 간격 예측 조위 |
| KHOA_OBSERVATION_SERVICE_KEY | 조위관측소 최신 관측데이터 관측 수위·수온·바람 |
| KHOA_BUOY_SERVICE_KEY | 해양관측부이 최신 관측데이터 파고·수온·바람 |
모두 무료로 안내되어 있습니다. 같은 인증키라도 API별 활용승인이 필요합니다. 관측 항목은 지점마다 다르며, TideBED 그래프와 부이 값은 별도 지점의 자료이므로 위치와 거리를 함께 확인해야 합니다.
다음으로 신청하면 좋은 API
- 조석예보(시계열) · 항구 지점 자체의 조위 그래프,
KHOA_TIDE_SERIES_SERVICE_KEY - 기상청 기상특보 · 풍랑·강풍·태풍 안내,
KMA_WARNING_SERVICE_KEY - 조류예보(시계열) · 유향·유속,
KHOA_CURRENT_SERVICE_KEY
이 세 항목은 선택 신청용 환경변수 입력칸만 준비되어 있으며 아직 연동하지 않았습니다.
운영 원칙
- 시간대는 Asia/Seoul, 조위 단위는 cm입니다.
- 출처: 해양수산부 국립해양조사원 조석예보(고·저조)
- 웹과 앱의 기본 주소를 api.물때정보.com으로 통일합니다.