기상청 API 뜻?

기상청 API 뜻: 단기·중기·실시간 예보 제공

기상청 API 뜻은 기상청 날씨 데이터를 응용프로그램에서 활용하기 위한 인터페이스입니다. 이 API는 단기예보, 중기예보, 실시간 관측 정보를 프로그램에 제공합니다. 여행, 농업, 물류 등 다양한 분야에서 기상 정보를 효과적으로 활용하는 데 필수적입니다. 정확한 데이터 사용을 위해 격자 좌표 체계 이해가 필요합니다.

기상청 API, 쉽게 풀어서 설명해 드립니다

날씨 앱을 켜면 현재 기온, 시간별 강수 확률, 주간 날씨까지 척척 보여줍니다. 이런 정보들은 하늘에서 뚝 떨어지는 게 아니라, 기상청이 보유한 방대한 데이터를 외부에서 가져와서 보여주는 건데요. 이때 핵심 역할을 하는 것이 바로 기상청 API 뜻입니다. 간단히 말해, 기상청 API는 기상청의 날씨 데이터를 우리가 만드는 프로그램이나 앱에서 가져다 쓸 수 있도록 열어놓은 데이터 통로이자 미리 정해진 규칙입니다.

기상청 API 뜻과 작동 방식

API는 Application Programming Interface의 줄임말로, 서로 다른 프로그램이 정해진 규칙에 따라 대화할 수 있게 해주는 접점입니다. 기상청 API에 빗대어 설명하면 이렇습니다. 여러분이 만든 앱(손님)이 기상청(식당 주방)에 날씨 정보(음식)를 요청하면, API(웨이터)가 이 요청을 받아 기상청 시스템에 전달하고, 그 결과를 다시 여러분의 앱에 가져다줍니다 (citation:1). 즉, 여러분은 복잡한 기상청 내부 시스템을 알 필요 없이, API라는 창구를 통해 원하는 날씨 데이터를 편리하게 가져올 수 있는 것입니다.

API를 통해 데이터를 주고받을 때는 보통 JSON 또는 XML 형식을 사용합니다. 마치 택배를 보낼 때 정해진 규격의 상자에 물건을 담는 것과 비슷합니다. 기상청 API도 마찬가지로, 기온, 강수량, 풍향 같은 데이터를 이 정해진 형식에 맞춰 우리에게 돌려줍니다. 우리 앱은 이 데이터를 받아서 사용자에게 보기 좋게 화면에 표시하기만 하면 됩니다.

기상청이 제공하는 주요 API 종류

기상청 API 허브를 살펴보면 정말 다양한 종류의 데이터를 API 형태로 제공하고 있음을 알 수 있습니다 (citation:5). 하지만 모든 API가 똑같이 쓰이진 않습니다. 일반적인 날씨 앱이나 서비스를 만든다면, 주로 다음과 같은 API들을 가장 많이 활용하게 됩니다.

단기예보 조회서비스: 현재로부터 3일간의 상세한 날씨를 알고 싶을 때 사용합니다. 3시간 단위로 기온, 강수 확률, 풍향, 풍속, 하늘 상태 등을 알 수 있으며, 하루에 8번(02, 05, 08, 11, 14, 17, 20, 23시) 업데이트됩니다 (^[1] citation:8). 가장 많이 쓰이는 API 중 하나입니다.

초단기예보 조회서비스: 지금 당장의 날씨가 궁금할 때 사용합니다. 과거 동네예보라는 이름으로 불리던 서비스로, 1시간 단위의 매우 짧은 시간의 강수량, 기온, 습도 등을 제공합니다. 보통 45분 또는 40분 주기로 업데이트되어 실시간에 가까운 날씨 정보를 얻을 수 있습니다 (citation:6)(citation:8).

중기예보 조회서비스: 일주일 뒤 여행 날씨가 궁금할 때 적합합니다. 4일 후부터 10일 후까지의 날씨 전망을 오전, 오후로 구분해 최저·최고 기온과 날씨 상태(맑음, 구름많음 등) 정보를 제공합니다. 하루에 두 번(06시, 18시) 업데이트됩니다 (citation:8).

실시간 관측정보 조회서비스: 현재 기상 상황을 가장 정확하게 반영합니다. 기상청의 관측 장비(AWS, ASOS 등)에서 측정한 현재 기온, 강수량, 풍향, 풍속 등을 10분 단위로 확인할 수 있습니다 (citation:8).

이 외에도 기상특보, 태풍 정보, 지진 정보, 해양 기상 데이터, 생활 기상 지수(자외선, 식중독 지수 등)까지 매우 다양한 API가 제공되므로, 만들고자 하는 서비스의 성격에 맞게 골라 사용할 수 있습니다 (citation:5).

처음 접하는 사람을 위한 기상청 API 용어 사전

기상청 API 가이드를 처음 보면 낯선 용어들 때문에 당황하기 쉽습니다. 몇 가지만 알아도 진입 장벽이 확 낮아지니, 주요 용어들을 간단히 정리해 보겠습니다.

인증키 (Service Key / AuthKey)

기상청 API를 사용하려면 반드시 필요한 출입증입니다. 공공데이터포털 또는 기상청 API허브에서 API 사용 신청을 하면 기상청 api 인증키 발급을 받을 수 있습니다 (citation:2)(citation:5). API를 호출할 때 이 키를 함께 보내야 정식 사용자로 인식되고 데이터를 받을 수 있습니다.

격자 좌표 (X, Y)

지도에서 위치를 나타낼 때 위도와 경도를 사용하듯, 기상청은 자체적인 격자 좌표계를 사용합니다. 예를 들어, 서울시청의 경우 위도 37.5665, 경도 126.9780을 기상청 격자 좌표로 변환하면 X=60, Y=127이 됩니다 (citation:8). API를 호출할 때는 이 격자 좌표 값을 필수 파라미터로 넘겨야 해당 위치의 날씨를 받을 수 있습니다.

Basedate와 Basetime

날씨 예보가 발표된 기준 날짜와 시간을 의미합니다. 예를 들어, 2월 15일 오전 11시에 발표된 예보를 원한다면 basedate=20250215, basetime=1100 과 같이 설정합니다. 이때 중요한 점은 발표 시각과 데이터가 실제로 존재하는 시간을 맞추는 것입니다. 예를 들어, 단기예보는 02시에 발표되므로, 새벽 1시에 오늘 날짜의 02시 데이터를 요청하면 아직 생성되지 않은 데이터를 요청하는 셈이 되어 에러가 날 수 있습니다 (citation:6).

카테고리 코드 (Category Code)

API 응답으로 오는 방대한 데이터에서 기온, 강수량 같은 특정 정보를 구분하기 위한 약어입니다. 주요 카테고리 코드는 다음과 같습니다 (citation:8).

TMP: 1시간 기온 (℃) REH: 습도 (%) POP: 강수 확률 (%) PTY: 강수 형태 (코드값: 0 없음, 1 비, 2 비/눈, 3 눈, 4 소나기) SKY: 하늘 상태 (코드값: 1 맑음, 3 구름많음, 4 흐림) PCP: 1시간 강수량 (mm) WSD: 풍속 (m/s)

Hello, Weather! 따라 하며 익히는 기상청 API

이론만으로는 감이 잘 안 올 수 있습니다. 가장 기본적인 단기예보 API를 호출해 실제 데이터를 받아보는 간단한 흐름을 따라가 보겠습니다. 여기서는 JavaScript의 fetch 함수를 예시로 들었지만, 다른 언어나 도구에서도 원리는 동일합니다.

1단계: 인증키 발급 및 준비 먼저 공공데이터포털 날씨 api 활용을 위해 data.go.kr에 접속해 회원가입을 하고, 기상청_단기예보 조회서비스 오픈 API를 활용신청합니다. 승인이 나면 마이페이지에서 일반 인증키(Encoding)를 복사해 둡니다 (citation:2). 이 키가 바로 API를 사용할 수 있는 열쇠입니다.

2단계: API 호출 URL 만들기 기상청 API 가이드에 나와 있는 엔드포인트(Endpoint, API 서버 주소)에 필수 파라미터들을 붙여서 실제 호출 URL을 만듭니다.

https://apis.data.go.kr/1360000/VilageFcstInfoService2.0/getVilageFcst?serviceKey=인증키&numOfRows=100&pageNo=1&dataType=JSON&basedate=20250215&base_time=0500&nx=60&ny=127

이 URL에는 다음과 같은 정보가 담겨 있습니다. serviceKey: 아까 복사해 둔 인증키 dataType=JSON: JSON 형식으로 데이터를 받겠다는 요청 basedate=20250215, basetime=0500: 2025년 2월 15일 오전 5시에 발표된 예보를 기준으로 nx=60, ny=127: 서울시청 좌표의 날씨 데이터를 numOfRows=100: 최대 100개까지 달라

3단계: 코드로 호출하고 결과 받기 이제 이 URL을 JavaScript 코드에서 호출해 봅시다.

javascript const APIKEY = 발급받은인증키값을여기에입력; const url = https://apis.data.go.kr/1360000/VilageFcstInfoService2.0/getVilageFcst?serviceKey=${APIKEY}&numOfRows=100&pageNo=1&dataType=JSON&basedate=20250215&base_time=0500&nx=60&ny=127; fetch(url) .then(response => response.json()) .then(data => { // 받아온 데이터 중 items 부분 출력 console.log(날씨 데이터:, data.response.body.items.item); }) .catch(error => { console.error(에러 발생:, error); });

4단계: 데이터 파싱하여 원하는 정보만 추출하기 실행 결과, 콘솔에는 여러 개의 객체가 담긴 배열이 출력될 것입니다. 각 객체는 baseDate, baseTime, category(TMP, PTY 등), fcstValue(예보 값) 등의 정보를 가지고 있습니다. 이 중에서 내 앱에 필요한 데이터, 예를 들어 오후 2시의 기온(TMP)만 걸러내어 화면에 표시하면 됩니다 (citation:8).

자주 발생하는 오류와 해결 방법 (트러블슈팅)

API 연동 중 가장 자주 마주치는 에러는 바로 30번, SERVICEKEYISNOTREGISTERED_ERROR (등록되지 않은 서비스키)입니다. 인증키에 문제가 있거나, 방금 발급받아서 기상청 서버에 키 정보가 아직 동기화되지 않았을 때 발생합니다 (citation:3). 보통 10~30분 정도 기다린 후 다시 시도하면 해결됩니다.

다음으로 흔한 에러는 01번 APPLICATIONERROR (어플리케이션 에러)입니다. 이는 대부분 basedate와 basetime을 잘못 설정했기 때문입니다 (citation:6). 예를 들어, 아직 발표되지 않은 미래 시각의 예보를 요청하거나, 날짜 형식을 YYYYMMDD로 정확히 맞추지 않았을 때 발생합니다. 현재 시간을 기준으로 유효한 basetime을 계산하는 로직을 정확히 구현해야 합니다 (citation:6).

또 다른 에러로는 04번 HTTP_ERROR가 있습니다. 이는 기상청 서버의 일시적인 장애나 네트워크 문제로 데이터를 받아오지 못할 때 발생합니다. 개발자 입장에서 직접 해결할 수 있는 방법은 없으며, 일정 시간이 지난 후 재요청을 시도하는 방식(Retry 로직)으로 대응해야 합니다 (citation:6).

내 상황에 딱 맞는 API, 어떻게 골라야 할까?

다양한 API 중 어떤 것을 선택해야 할지 막막하다면, 다음 질문을 스스로에게 던져보세요.

지금 이 순간의 날씨가 가장 중요하다면? → 초단기예보 또는 실시간 관측정보 API가 정답입니다. 초단기예보는 실시간에 가까운 예측값을, 실시간 관측정보는 관측 장비가 측정한 실제 값을 보여줍니다.

오늘 나갈 외출이나 일정을 위해 오후까지의 날씨가 궁금하다면? → 단기예보 API를 선택하세요. 3일간의 상세한 날씨를 3시간 단위로 알려줘서 충분합니다.

다음 주 여행이나 캠핑 계획을 세우고 있다면? → 중기예보 API가 필요합니다. 4일 후부터 10일 후까지의 날씨 경향을 파악하는 데 유용합니다.

산업, 농업, 해양 등 특화된 정보가 필요하다면? → 기상청 API허브에서 제공하는 모든 API 목록을 살펴보세요. 태양광 발전을 위한 일사량, 농사를 위한 토양 온도, 항해를 위한 파고 정보 등 전문화된 API가 준비되어 있습니다 (citation:5).

마치며: API 문턱, 생각보다 낮습니다

처음엔 API라는 단어부터 인증키, 격자 좌표 같은 용어들이 복잡하게 느껴져 막막할 수 있습니다. 하지만 이 글에서 살펴본 것처럼, 기상청 api 란 결국 기상청 데이터를 내 앱에서 쓸 수 있도록 만든 정해진 규칙과 통로에 불과합니다. 공공데이터포털에서 인증키를 받고, 제공되는 예제 코드를 하나씩 따라 하다 보면 생각보다 훨씬 쉽게 첫 데이터를 받아볼 수 있을 것입니다. 작은 성공 경험을 발판삼아, 이제 여러분만의 멋진 날씨 서비스를 만들어 보시길 바랍니다.

기상청 주요 날씨 API 한눈에 비교하기

초단기예보

• 지금 비가 오는지, 1시간 후에는 기온이 몇 도인지

• 실시간에 가까운 1~6시간

• 기온, 강수량, 강수형태, 습도, 풍향, 풍속 등

• 매시간 40~45분경 업데이트

단기예보

• 오늘 오후 3시에 비가 올 확률, 내일 아침 최저 기온

• 오늘부터 3일 후까지

• 3시간 단위 기온, 강수확률, 하늘상태, 풍향, 풍속 등

• 하루 8회 (02, 05, 08, 11, 14, 17, 20, 23시)

중기예보

• 일주일 뒤 소풍 날씨가 맑을지, 다음 주말 기온은 몇 도일지

• 4일 후부터 10일 후까지

• 오전/오후 날씨 상태, 최저/최고 기온

• 하루 2회 (06, 18시)

서울 청년창업가 지원사: 우리 동네 산책 날씨 알림 서비스 '산책갈까' 개발기

서울에서 1인 창업을 준비 중인 김지후 대표는 직장인들을 위한 '산책갈까'라는 간단한 알림 서비스를 기획했습니다. 사용자가 설정한 동네의 저녁 시간(오후 7~9시) 날씨가 맑고 강수 확률이 낮으면 푸시 알림을 보내주는 서비스였습니다. 문제는 API 선정이었습니다. 다양한 기상청 API 중 어떤 것을 써야 할지, 용어들은 너무 낯설게만 느껴졌습니다.

처음에는 가장 유명한 '단기예보' API를 선택했습니다. 그런데 막상 구현하고 보니, 저녁 7시에 보내는 알림이 오전에 발표된 오래된 예보 데이터를 기반으로 하는 경우가 많았습니다. 사용자들은 "비가 온다고 해서 우산 챙겼는데 왜 맑죠?"라는 불만을 남겼고, 서비스 신뢰도는 급격히 떨어졌습니다. 밤을 새며 오류를 뒤져봤지만 원인을 찾지 못해 큰 좌절감을 느꼈습니다.

며칠간의 디버깅 끝에, 김 대표는 기상청 API 가이드에서 '초단기예보'의 존재를 발견했습니다. 초단기예보는 1시간마다 업데이트되어 현재 날씨에 훨씬 가까운 정보를 준다는 사실을 알게 되었습니다. 바로 API를 초단기예보로 교체하고, 알림을 보내는 시간(오후 6시 50분경)에 맞춰 가장 최신의 base_time(오후 6시에 발표된 데이터)을 계산하는 로직을 구현했습니다.

결과는 놀라웠습니다. 교체 후 '산책갈까'의 알림 적중률은 이전보다 훨씬 높아졌고, 사용자들의 긍정적인 후기가 늘기 시작했습니다. 김 대표는 이 경험을 통해 "유명한 API보다 내 서비스의 시간대와 목적에 정확히 맞는 API를 선택하는 것이 훨씬 중요하다"는 교훈을 얻었습니다. 단순한 아이디어였던 서비스는 현재 5,000명의 월간 활성 사용자를 확보하며 안정적으로 운영 중입니다.