목차
기상청 API는 주소를 넣고 바로 끝나는 구조가 아니다. 격자 좌표, 발표 시각, 자료 종류가 맞물려야 실시간에 가까운 날씨 데이터를 얻는다. 공공데이터포털 전환으로 같은 이름의 서비스라도 접근 경로가 달라진다.
실무에서 많이 부딪히는 지점은 데이터 자체보다 호출 조건이다. 동네예보, 초단기실황, 생활기상지수, 도로위험기상정보가 각각 다른 방식으로 움직이고, 기상청 API 허브와 공공데이터포털의 역할도 분리되어 있다. 한 번에 하나의 화면으로 보이게 설계한 서비스와 달리, 호출용 API는 목적별 분화가 강하다.
기상청 API를 처음 붙일 때 중요한 값은 세 가지다. 어떤 서비스가 필요한지, 어느 좌표를 넣을지, 어느 시각의 발표 자료를 읽을지다. 이 셋이 맞지 않으면 응답은 와도 쓸 수 없는 데이터가 된다.
실시간 데이터 구조와 호출 단위
기상청 API에서 실시간이라는 표현은 화면 갱신 속도를 뜻하지 않는다. 자료가 관측되고, 집계되고, 발표된 뒤 호출되는 방식이기 때문에 초단위 생중계와는 다르다. 초단기실황은 현재 관측값에 가깝고, 초단기예보는 짧은 시간 간격의 예측값에 가깝다.
동네예보는 시간대별 기온, 강수확률, 하늘상태를 묶어 제공한다. 중기예보는 3일 이후 10일 이내 구간을 다루는 식으로 범위가 넓어지고, 생활기상지수는 불쾌지수나 자외선처럼 생활 체감형 정보로 분리된다. 같은 기상청 API라도 데이터 단위가 다르다.
실시간 처리에서 자주 쓰는 기준은 관측 시각과 발표 시각이다. 예보는 정해진 시각에 갱신되며, 그 이전에는 직전 발표분을 읽어야 한다. 19시 조회 시 17시 자료를 쓰는 식의 시간 기준이 들어가면 호출 로직이 단순 조회에서 운영 로직으로 바뀐다.
공공데이터포털 전환과 신청 경로
기상청 오픈API 서비스 방식은 공공데이터포털 게이트웨이 모듈 적용 방식으로 전환되었다. 공공데이터포털에서 새로 전환된 서비스를 활용 신청해 쓰는 구조다. 그래서 같은 기상청 API라도 신규 신청 절차를 거쳐야 한다.
신청 경로는 공공데이터포털에서 기상청 관련 서비스를 찾고, 활용 신청을 거쳐 인증키를 받는 방식이다. 기상청 API 허브에는 지상관측, 해양관측, 고층관측, 레이더, 위성, 지진·화산, 태풍, 수치모델, 예특보, 융합기상, 항공기상, 세계기상, 산업특화 API가 나뉘어 있다. 목적에 맞는 항목을 고르는 과정이 먼저다.
생활기상지수나 도로위험기상정보처럼 이름이 비슷한 데이터도 실제 제공 범위가 다르다. 융합기상 도로위험기상정보는 고속도로에 설치된 도로 CCTV 영상을 활용해 안개, 비, 눈 정보를 생산한다. 단순 날씨 조회와는 성격이 다르다.
좌표와 코드 체계가 만드는 차이
기상청 API는 주소 문자열만 넣는 구조가 아니다. 동네예보는 격자 번호를 쓰고, 육상예보와 중기예보는 예보구역코드를 사용한다. 특보는 특보구역코드가 따로 붙는다. 같은 서울이라도 데이터 종류에 따라 식별자가 달라진다.
이 차이는 실시간 데이터 구성에서 가장 큰 분기점이다. 위경도는 먼저 어떤 코드로 변환할지 정해야 한다. 일부 서비스는 위경도 변환 API를 제공하지만, 일부는 행정구역명이나 관측소 코드에 더 가깝게 움직인다.
도로위험기상정보처럼 현장 기반 서비스는 더 까다롭다. 고속도로 구간과 CCTV 영상이 결합된 형태이기 때문에 일반 예보처럼 단순 지역명으로 접근하기 어렵다. 기상청 API를 한 묶음으로 보면 편해 보이지만, 실제로는 코드 체계가 다층 구조다.
발표 시각과 갱신 주기 처리
실시간 날씨 데이터를 안정적으로 받으려면 갱신 시각을 먼저 알아야 한다. 동네예보는 02시, 05시, 08시, 11시, 14시, 17시, 20시, 23시처럼 하루 8번 갱신되는 구조가 대표적이다. 호출 시각이 갱신 직후가 아니면 직전 자료를 읽는 편이 맞다.
기온, 강수형태, 하늘상태처럼 항목별 발표 기준이 다른 경우도 있다. 최저기온과 최고기온은 특정 기준 시각에서만 확보되는 구조가 흔하고, 시간대별 자료와 분리해 처리해야 한다. 한 번의 호출로 모든 항목이 같은 시각 기준으로 들어오지 않는 셈이다.
이 때문에 자동화에서는 현재 시각 보정이 들어간다. KST 기준 시간 변환, 발표 시각 체크, 데이터 미존재 예외 처리가 함께 들어가야 한다. 기상청 API를 단순 REST 호출로만 보면 실패 원인을 찾기 어렵다.
자주 막히는 오류와 응답 처리
가장 많이 걸리는 문제는 인증키보다 시각과 좌표다. 키가 유효해도 발표 시각이 맞지 않으면 빈값이 나오고, 코드가 틀리면 엉뚱한 지역 데이터가 들어온다. 응답이 정상이어도 파싱 결과가 비는 경우가 생긴다.
응답 형식도 서비스마다 다르다. JSON으로 내려오는 항목이 많지만, 항목명과 코드값 해석은 별도 매뉴얼을 봐야 한다. 예보버전조회, 단기개황, 동네예보분포처럼 이름이 비슷한 API가 많아도 목적이 서로 다르다.
기상청 API를 운영에 붙일 때는 재시도 정책과 캐시도 중요하다. 실시간성만 강조하면 호출 실패가 곧 서비스 실패로 이어진다. 일정 시간 동안 직전 응답을 유지하고, 갱신 시각 이후에만 새 값을 덮어쓰는 구조가 안정적이다.
도메인별 활용 포인트 정리
기상 데이터는 용도에 따라 읽는 방식이 달라진다. 날씨 알림 봇은 초단기예보와 동네예보가 핵심이고, 해상 운항은 해양관측과 태풍 정보가 더 중요하다. 도로 서비스는 강수, 적설, 안개 같은 현장 지표를 우선 본다.
산업 특화 영역에서도 기상청 API의 쓰임은 넓다. 선박 운항 일정 자동화처럼 기상정보와 외부 위치정보 API를 연결해 입항 시간을 계산하는 사례가 나온다. 기상 데이터는 운영 변수다.
API 허브의 분화는 번거롭게 보이지만, 목적이 분리되어 있다는 뜻이기도 하다. 관측, 예보, 특보, 융합기상, 항공기상, 세계기상은 각기 다른 갱신 주기와 해석 규칙을 가진다. 기상청 API를 실시간 데이터로 쓴다는 말은 이 구조를 함께 다룬다는 뜻이다.
실전 호출에서 보는 데이터 선택
개발 화면에서 먼저 골라야 하는 것은 예쁘게 보이는 데이터가 아니다. 현재값이 필요한지, 1시간 뒤가 필요한지, 3일 예보가 필요한지부터 정해야 한다. 기상청 API는 이 목적 분리에 매우 엄격하다.
실무에서 자주 조합되는 항목은 기온, 강수확률, 하늘상태, 풍속, 습도다. 생활기상지수까지 붙이면 체감형 안내가 가능하고, 도로위험기상정보까지 붙이면 이동 안전 정보로 확장된다. 같은 날씨라도 쓰는 값이 다르다.
기상자료개방포털의 Open API 활용신청 안내와 기상청 API 허브의 서비스 목록을 같이 보는 이유도 여기 있다. 신청 경로와 제공 범위는 분리해 봐야 호출 후 해석이 맞는다. 구조를 먼저 정리하지 않으면 데이터가 많아도 쓸 수 있는 값은 적다.
자주 묻는 질문
Q. 기상청 API와 기상청 API 허브는 같은 의미인가
같은 의미로 쓰이기도 하지만 범위는 다르다. 허브는 여러 관측, 예보, 특보, 융합기상 서비스를 묶어 보여주는 진입점이고, 실제 호출은 공공데이터포털 전환 서비스나 허브 개별 안내를 따라간다.
Q. 실시간 날씨 데이터는 어떤 API가 기본인가
현재 관측에 가까운 값은 초단기실황이 기본 축이 되고, 짧은 예측값은 초단기예보와 동네예보가 함께 쓰인다. 필요한 시점이 현재인지, 가까운 미래인지에 따라 선택이 갈린다.
Q. 주소만 넣으면 지역 날씨가 바로 나오나
그 방식은 잘 맞지 않는다. 동네예보는 격자 번호, 육상예보와 중기예보는 예보구역코드처럼 별도 코드가 필요하고, 일부 서비스는 발표관서코드나 특보구역코드를 쓴다.
Q. 공공데이터포털 전환 후 기존 키를 그대로 써도 되나
전환된 서비스는 신규 활용신청을 거쳐 써야 하는 경우가 많다. 새로 전환된 API를 신청해 인증키를 받는 구조로 본다.
Q. 호출은 정상인데 데이터가 비는 이유는 무엇인가
발표 시각이 맞지 않거나, 조회 시점이 갱신 전이거나, 좌표 코드가 틀린 경우가 많다. 최저기온과 최고기온처럼 특정 시각 기준으로만 나오는 항목도 있어 단순 응답 성공만으로는 충분하지 않다.
기상청 API를 실시간 날씨 데이터로 쓰려면 응답 포맷보다 호출 규칙을 먼저 읽어야 한다. 격자 번호, 예보구역코드, 발표 시각, 공공데이터포털 전환 방식이 맞물리며, 이 구조를 이해해야 현재값과 예보값을 함께 다룰 수 있다. 기상청 API는 코드와 시간 설계가 중요한 서비스다.
