기상청 동네예보 API는 동네 단위의 상세한 날씨 예보 데이터를 제공하는 공공 API로, 날씨 앱이나 서비스를 개발할 때 꼭 필요한 리소스예요. 공공데이터포털을 통해 무료로 신청할 수 있고, 격자 좌표 기반으로 전국 어디서든 정확한 날씨 데이터를 가져올 수 있어요. 개발자라면 한 번쯤 활용해보고 싶은 API인데, 처음 접하면 좌표 변환이나 API 구조가 낯설게 느껴질 수 있어요.
이 글에서는 기상청 동네예보 API를 처음 사용하는 개발자를 위해 신청 방법부터 응답 데이터 구조 이해, 실제 활용 방법까지 단계별로 자세히 설명해드릴게요.
기상청 동네예보 API란
이 부분은 매우 중요한 영역이에요. 실제 상황에서 이를 제대로 이해하고 적용하는 것이 성공의 핵심이라고 할 수 있어요.
동네예보 API 개요
기상청 동네예보 API는 기상청이 공공데이터포털을 통해 제공하는 날씨 예보 데이터 서비스예요. 전국을 5km×5km 격자로 나누어 각 격자 단위로 기온, 강수량, 습도, 풍속, 풍향, 하늘 상태 등 다양한 기상 요소의 예보 데이터를 제공해요. 실시간 관측 데이터가 아니라 예보 데이터라는 점이 특징이고, 초단기 예보(6시간 이내), 단기 예보(3일 이내), 중기 예보(10일 이내) 등 다양한 예보 구간이 있어요.
이 API는 한국기상산업기술원의 기상자원개방포털과 공공데이터포털 두 곳에서 제공되는데, 일반적으로 공공데이터포털(data.go.kr)을 통해 신청하는 게 더 간편하고 많이 사용돼요.
제공 데이터 종류
- 초단기실황 조회: 현재 기상 상태 (1시간 단위, 최근 1시간 실황)
- 초단기예보 조회: 6시간 이내 예보 (30분 단위 갱신)
- 단기예보 조회: 3~5일 예보 (매일 02/05/08/11/14/17/20/23시 갱신)
- 중기예보: 10일 예보 (별도 중기예보 API)
공공데이터포털에서 API 신청하기
이 부분은 매우 중요한 영역이에요. 실제 상황에서 이를 제대로 이해하고 적용하는 것이 성공의 핵심이라고 할 수 있어요.
신청 절차 단계별 가이드
기상청 동네예보 API를 사용하려면 먼저 공공데이터포털(data.go.kr)에 회원 가입하고 API를 신청해야 해요. 포털에 로그인 후 검색창에 “기상청 단기예보” 또는 “동네예보”로 검색하면 “기상청_단기예보 ((구)동네예보) 조회서비스” API를 찾을 수 있어요. 상세 페이지에서 “활용신청” 버튼을 클릭하면 신청 양식이 나와요.
신청 양식에는 활용 목적, 개발 내용, 서비스 유형 등을 기재해야 해요. 개인 개발자도 신청할 수 있고, 신청 후 심사를 거쳐 API 키(Service Key)가 발급돼요. 심사는 보통 1~3일 내에 완료되고, 승인되면 마이페이지에서 API 키를 확인할 수 있어요.
신청 시 주의사항
- 활용 목적을 구체적으로 작성할수록 승인이 빨라요
- 일일 요청 한도가 있으니 활용 계획에 맞게 신청
- 서비스 키는 URL 인코딩된 형태로 발급 (디코딩해서 사용)
- 트래픽이 많은 서비스라면 유료 전환 또는 추가 한도 신청 필요
격자 좌표 시스템 이해하기
이 부분은 매우 중요한 영역이에요. 실제 상황에서 이를 제대로 이해하고 적용하는 것이 성공의 핵심이라고 할 수 있어요.
격자 좌표란 무엇인가요
기상청 동네예보 API는 일반적인 위도·경도 좌표가 아니라 기상청 자체 격자 좌표(X, Y)를 사용해요. 전국을 5km 간격으로 격자화한 후 각 격자에 X, Y 값을 할당한 시스템이에요. 이 때문에 우리가 알고 있는 위도·경도를 격자 좌표로 변환하는 과정이 필요해요.
예를 들어 서울 중구의 경우 위도 37.5663, 경도 126.9779이지만, 동네예보 API에서는 이를 격자 좌표 X=60, Y=127로 변환해서 요청해야 해요. 이 변환 공식은 기상청에서 제공하는 기술 문서에 포함되어 있어요.
위도경도 → 격자좌표 변환 방법
기상청은 위도·경도를 격자 좌표로 변환하는 공식과 변환 코드를 기술 문서와 함께 배포해요. 주요 지역의 격자 좌표는 기상청 API 기술 문서에 표 형태로 정리되어 있어서 자주 사용하는 지역은 미리 확인해두면 편리해요. 프로그래밍으로 변환이 필요한 경우, 기상청 제공 변환 코드(Python, Java 등)를 활용하거나 공개된 변환 라이브러리를 이용할 수 있어요.
- 서울 중구: X=60, Y=127
- 부산 해운대: X=99, Y=75
- 제주 제주시: X=52, Y=38
- 기상청 기술 문서에서 주요 지역 격자 좌표표 확인 가능
API 요청 방법과 파라미터
이 부분은 매우 중요한 영역이에요. 실제 상황에서 이를 제대로 이해하고 적용하는 것이 성공의 핵심이라고 할 수 있어요.
기본 요청 구조
기상청 동네예보 API는 HTTP GET 방식으로 요청해요. 기본 엔드포인트 URL에 쿼리 파라미터를 붙여서 요청하면 되고, 응답은 JSON 또는 XML 형식으로 받을 수 있어요. 주요 파라미터는 서비스 키(ServiceKey), 날짜(base_date), 시각(base_time), 격자 X 좌표(nx), 격자 Y 좌표(ny), 페이지 번호(pageNo), 한 페이지 결과 수(numOfRows), 응답 형식(dataType)이에요.
예를 들어 2026년 5월 25일 오전 8시 기준의 서울 날씨를 조회하려면 base_date=20260525, base_time=0800, nx=60, ny=127 파라미터를 포함해 요청하면 돼요. 단기예보의 경우 base_time은 0200, 0500, 0800, 1100, 1400, 1700, 2000, 2300 중 하나여야 해요.
응답 데이터 항목(카테고리) 설명
- T1H/TMP: 기온(°C) – 실황/단기 예보
- RN1/PCP: 1시간 강수량(mm)
- REH: 습도(%)
- WSD: 풍속(m/s)
- VEC: 풍향(°)
- SKY: 하늘 상태 (1:맑음, 3:구름많음, 4:흐림)
- PTY: 강수 형태 (0:없음, 1:비, 2:비/눈, 3:눈, 4:소나기)
- POP: 강수 확률(%)
API 응답 데이터 처리
이 부분은 매우 중요한 영역이에요. 실제 상황에서 이를 제대로 이해하고 적용하는 것이 성공의 핵심이라고 할 수 있어요.
JSON 응답 구조 파악하기
기상청 동네예보 API의 JSON 응답은 response → body → items → item 구조로 되어 있어요. item 배열에 각 예보 항목들이 담겨 있고, 각 항목은 예보 날짜(fcstDate), 예보 시각(fcstTime), 카테고리(category), 예보 값(fcstValue) 등의 필드로 구성돼요. 한 번의 API 요청에 여러 카테고리의 데이터가 포함되어 있기 때문에 카테고리 값을 필터링해서 원하는 기상 요소를 추출해야 해요.
응답 코드 확인도 중요해요. resultCode가 “00”이면 정상 응답이고, 다른 코드면 오류 상황이에요. 주요 오류 코드로는 “01”(APPLICATION_ERROR), “02”(DB_ERROR), “03”(NODATA_ERROR), “04”(HTTP_ERROR) 등이 있어요. 오류 처리 로직을 반드시 구현해두는 게 좋아요.
데이터 처리 시 주의사항
- 요청 시각과 API 갱신 시각이 맞지 않으면 NODATA 오류 발생
- numOfRows 기본값이 10으로 작으므로 충분한 수로 설정 필요
- 서비스 키는 URL 인코딩 상태 또는 디코딩 상태를 구분해서 사용
- API 호출 빈도 제한(일일 쿼터) 초과 시 요청 차단
활용 사례와 아이디어
이 부분은 매우 중요한 영역이에요. 실제 상황에서 이를 제대로 이해하고 적용하는 것이 성공의 핵심이라고 할 수 있어요.
날씨 앱 개발에 활용
기상청 동네예보 API는 날씨 앱, 농업 관련 서비스, 야외 이벤트 알림 서비스, 운동 스케줄 도우미 등 다양한 애플리케이션에 활용할 수 있어요. 특히 농업 분야에서는 지역별 세밀한 날씨 예보가 작물 관리에 매우 중요하고, 건설 현장 관리 시스템에서도 날씨 데이터가 필수적이에요.
개인 프로젝트로도 활용 범위가 넓어요. 라즈베리파이나 아두이노 같은 임베디드 시스템에 날씨 데이터를 연동하거나, 카카오 채널 봇에 날씨 정보를 통합하는 등 창의적인 활용이 가능해요. 기상 데이터를 시각화해서 대시보드를 만드는 것도 인기 있는 활용 방법이에요.
마무리
이 부분은 매우 중요한 영역이에요. 실제 상황에서 이를 제대로 이해하고 적용하는 것이 성공의 핵심이라고 할 수 있어요.
기상청 동네예보 API는 정확한 한국 날씨 데이터를 무료로 활용할 수 있는 매우 유용한 공공 API예요. 처음에는 격자 좌표 변환이나 API 구조가 낯설게 느껴질 수 있지만, 기상청에서 제공하는 기술 문서와 샘플 코드를 참고하면 빠르게 이해할 수 있어요.
공공데이터포털에서 신청하면 무료로 사용할 수 있으니, 날씨 관련 서비스나 프로젝트를 계획 중이라면 꼭 활용해보세요. 기상청의 공신력 있는 날씨 데이터를 기반으로 더 정확하고 유용한 서비스를 만들어나갈 수 있을 거예요.