기상청 API를 사용하고 싶지만 어디서부터 시작해야 할지 모르겠다는 분들이 많아요. 공공데이터포털에서 신청하는 방법, 발급받은 키로 실제 호출하는 방법, 결과를 파싱하는 방법까지 한번 막히면 진도가 나가지 않는 경우가 많죠.
이 글에서는 기상청 API를 처음 사용하는 분을 위해 공공데이터포털 가입부터 실제 데이터를 가져오는 단계까지 차근차근 설명해드릴게요.
사전 준비: 공공데이터포털 회원가입
기상청 API를 사용하려면 먼저 공공데이터포털(data.go.kr)에 회원가입이 필요해요.
회원가입 절차
- data.go.kr 접속 후 우측 상단 ‘회원가입’ 클릭
- 개인 회원 또는 기관 회원 선택 (개인 개발자는 개인 회원으로 가입)
- 이메일 주소 입력 후 인증 메일 확인
- 기본 정보 입력 및 약관 동의
- 회원가입 완료 후 로그인
API 서비스 검색 및 신청
로그인 후 검색창에 ‘기상청’을 입력하면 기상청이 제공하는 다양한 API 목록이 나타나요. 사용하려는 서비스를 클릭하고 상세 페이지에서 ‘활용신청’ 버튼을 눌러요. 활용 목적과 간단한 활용 계획을 기입하고 신청하면 대부분 즉시 또는 1~2일 이내에 승인돼요.
인증키 발급 확인
승인이 완료되면 마이페이지 → 데이터 활용 → 오픈 API에서 발급된 인증키를 확인할 수 있어요. 인증키는 긴 영문자·숫자 조합이에요. 이 키를 안전하게 보관하세요.
주요 API 소개: 단기예보 조회서비스
가장 많이 사용되는 기상청 API는 ‘기상청_단기예보_조회서비스’예요. 이 API를 기준으로 사용 방법을 설명해드릴게요.
API 기본 정보
- 서비스명: 기상청_단기예보_조회서비스
- 오퍼레이션: getVilageFcst (단기예보 조회), getUltraSrtFcst (초단기예보 조회), getUltraSrtNcst (초단기실황 조회)
- 기본 URL: https://apis.data.go.kr/1360000/VilageFcstInfoService_2.0/
- 응답 형식: JSON 또는 XML (파라미터로 선택)
요청 파라미터
- serviceKey: 발급받은 인증키 (URL 인코딩 주의)
- pageNo: 페이지 번호 (기본값 1)
- numOfRows: 한 페이지 결과 수 (최대 1000)
- dataType: 응답 형식 (JSON 또는 XML)
- base_date: 발표 날짜 (YYYYMMDD 형식)
- base_time: 발표 시각 (0200, 0500, 0800, 1100, 1400, 1700, 2000, 2300 중 하나)
- nx: 예보 지점 X 격자값
- ny: 예보 지점 Y 격자값
격자 좌표 변환 방법
기상청 API는 위·경도가 아닌 격자 좌표(nx, ny)를 사용해요. 이 부분에서 처음 사용하는 분들이 가장 많이 막혀요.
주요 도시 격자 좌표 참고
- 서울: nx=60, ny=127
- 부산: nx=98, ny=76
- 대구: nx=89, ny=90
- 인천: nx=55, ny=124
- 광주: nx=58, ny=74
- 대전: nx=67, ny=100
- 울산: nx=102, ny=84
- 세종: nx=66, ny=103
- 제주: nx=52, ny=38
위·경도 → 격자 좌표 변환 코드
기상청 공식 문서에 Python, Java 등 다양한 언어로 작성된 변환 코드가 제공돼요. 변환에 필요한 상수값(격자 간격, 기준점 위도·경도 등)도 공식 문서에 나와 있어요. GitHub에서 ‘기상청 격자 변환’으로 검색하면 공개된 변환 함수 라이브러리를 찾을 수 있어요.
실제 API 호출 예시
Python을 기준으로 기상청 단기예보 API를 호출하는 방법을 설명해드릴게요.
requests 라이브러리 활용
Python에서 HTTP 요청을 보내려면 requests 라이브러리를 사용해요. 설치는 pip install requests로 간단하게 할 수 있어요. API 요청 구조는 다음과 같아요.
- API 기본 URL을 변수에 저장해요
- 파라미터 딕셔너리를 만들어 serviceKey, base_date, base_time, nx, ny 등을 입력해요
- requests.get(url, params=params)으로 요청을 보내요
- 응답 JSON을 파싱해 필요한 데이터를 추출해요
인증키 URL 인코딩 주의사항
공공데이터포털에서 발급된 인증키는 일반 인코딩 키와 인코딩되지 않은 키 두 가지가 있어요. requests 라이브러리를 사용할 때는 인코딩되지 않은 키(Decode 키)를 사용해야 해요. 인코딩 키를 params로 전달하면 이중 인코딩이 되어 인증 오류가 발생할 수 있어요.
응답 데이터 구조
JSON 응답의 기본 구조는 다음과 같아요.
- response.header.resultCode: 결과 코드 (00이면 성공)
- response.header.resultMsg: 결과 메시지
- response.body.items.item: 실제 날씨 데이터 배열
각 item은 category(데이터 구분), fcstDate(예보 날짜), fcstTime(예보 시간), fcstValue(예보 값)로 구성돼요.
응답 데이터 파싱과 활용
API로 받아온 데이터를 이해하고 원하는 정보를 추출하는 방법을 설명해드릴게요.
주요 카테고리 코드
- TMP: 기온 (섭씨)
- TMN: 일 최저 기온 (섭씨)
- TMX: 일 최고 기온 (섭씨)
- POP: 강수 확률 (%)
- PTY: 강수 형태 (0:없음, 1:비, 2:비/눈, 3:눈, 4:소나기)
- PCP: 1시간 강수량 (mm)
- REH: 습도 (%)
- SKY: 하늘 상태 (1:맑음, 3:구름많음, 4:흐림)
- WSD: 풍속 (m/s)
- VEC: 풍향 (0~360도)
특정 날짜·시간 데이터 추출
item 배열에서 원하는 날짜(fcstDate)와 시간(fcstTime)을 가진 항목을 필터링하면 특정 시점의 날씨 데이터를 얻을 수 있어요. Python이라면 리스트 컴프리헨션이나 pandas DataFrame을 활용하면 효율적이에요.
오류 처리
API 응답에서 resultCode가 00이 아닐 경우 오류가 발생한 것이에요. 자주 발생하는 오류 코드와 원인은 다음과 같아요.
- 01: 어플리케이션 에러 (파라미터 오류 가능성)
- 02: DB 에러
- 03: 데이터없음 (요청한 base_date·base_time에 데이터가 없는 경우)
- 10: 잘못된 요청 파라미터
- 20: 서비스 종료
- 22: 서비스 요청 초과 (일일 호출 한도 초과)
실용적인 활용 팁
기상청 API를 효율적으로 사용하기 위한 실용적인 팁을 정리했어요.
base_time 선택 요령
단기예보는 하루 8번 발표돼요. 현재 시간에 가장 가까운 발표 시각을 base_time으로 사용해야 가장 최신 데이터를 받을 수 있어요. 발표 직후(약 10분 이내)에는 데이터 준비가 안 됐을 수 있으니, 10~15분 후에 조회하는 것을 권장해요.
캐싱으로 API 호출 절약
날씨 데이터는 발표 시각(매 3시간)마다 갱신돼요. 그 사이에는 데이터가 변하지 않으므로, 매번 API를 호출하지 않고 결과를 캐시에 저장해 재활용하면 불필요한 호출을 줄일 수 있어요. Redis, 파일 캐시, 메모리 캐시 등을 활용해요.
트래픽 증량 신청
기본 제공 트래픽이 부족하면 공공데이터포털 마이페이지에서 트래픽 증량을 신청할 수 있어요. 서비스 규모와 목적을 기재해 신청하면 무료로 증량이 가능한 경우가 많아요.
테스트 환경 구성
실제 서비스에 연결하기 전에 Postman이나 curl 같은 도구로 API 응답을 먼저 확인해보는 것이 좋아요. 응답 구조를 파악한 후 코드를 작성하면 오류를 줄일 수 있어요.
마무리
기상청 API는 처음 진입 장벽이 있지만, 공공데이터포털에서 신청하고 격자 좌표 변환 방법만 익히면 다양한 날씨 데이터를 자유롭게 활용할 수 있어요.
단기예보 API부터 시작해서 초단기 실황, 중기예보 API로 확장해가면서 필요한 날씨 서비스를 직접 만들어보세요. 공공데이터포털의 상세 문서와 샘플 코드를 적극 활용하면 훨씬 빠르게 시작할 수 있어요.