기상청 단기예보 API 사용법

1. 공공데이터포털 가입 및 서비스 신청 절차

기상청 기상 데이터를 사용하기 위해서는 먼저 공공데이터포털에서 인증키(Service Key)를 발급받아야 합니다.

1. 공공데이터포털 접속 및 로그인: 공공데이터포털에 접속하여 회원가입 후 로그인을 진행합니다.
2. 데이터 검색: 검색창에 "단기예보 조회서비스"를 입력하여 검색합니다.
3. 활용신청: 검색 결과에서 '기상청_단기예보 조회서비스'를 선택한 후 오른쪽의 [활용신청] 버튼을 클릭합니다.
4. 상세기능 선택: 신청 시 활용 목적을 작성하고, 필요한 상세 기능(초단기실황, 초단기예보, 단기예보 등)을 모두 체크합니다.
5. 승인 및 인증키 확인: 신청 즉시 혹은 수일 내에 승인이 완료됩니다. [마이페이지] > [오픈API] > [개발계정]에서 발급된 '인증키(Encoding/Decoding)'를 확인할 수 있습니다.
   • 주의: Python requests 라이브러리 사용 시 주로 Decoding 키를 사용하지만, 환경에 따라 Encoding 키가 필요할 수 있습니다.

---

2. 기상청 단기예보 오픈 API 개요

본 가이드는 제공된 문서의 단기예보 조회서비스(2.0)를 기준으로 합니다.

• 서비스 URL: http://apis.data.go.kr/1360000/VilageFcstInfoService_2.0
• 주요 상세 기능:

1. 초단기실황조회 (getUltraSrtNcst): 현재 시점의 실측 관측값 제공.
   
    
2. 초단기예보조회 (getUltraSrtFcst): 현재 시점부터 6시간 이내의 예보 제공.
   
    
3. 단기예보조회 (getVilageFcst): 예보기간과 구역을 시공간적으로 세분화한 예보(기존 '동네예보') 제공.

---

3. Python 구현 예제 코드

이 코드는 '단기예보조회(getVilageFcst)' 기능을 사용하여 특정 지역의 기온(TMP), 강수확률(POP) 등을 가져오는 예제입니다.

필수 라이브러리 설치

Bash

 

pip install requests

전체 소스 코드

Python

 

import requests
import json
from datetime import datetime

def get_weather_forecast(service_key, nx, ny):
    """
    기상청 단기예보 API를 호출하여 예보 데이터를 반환하는 함수
    """
    # 1. API 접속 정보 설정
    url = 'http://apis.data.go.kr/1360000/VilageFcstInfoService_2.0/getVilageFcst'
    
    # 2. 발표일자 및 시각 설정 (문서 참고)
    # 단기예보는 02, 05, 08, 11, 14, 17, 20, 23시에 발표됨
    now = datetime.now()
    base_date = now.strftime("%Y%m%d") # 예: 20241128
    
    # 실제 구현 시에는 현재 시간 기준으로 가장 최근 base_time을 계산해야 함
    # 예시를 위해 오전 5시 발표 자료를 기준으로 설정
    base_time = "0500" 
    
    # 3. 요청 파라미터 구성
    params = {
        'serviceKey' : service_key,
        'pageNo' : '1',
        'numOfRows' : '1000', # 충분한 데이터를 가져오기 위해 크게 설정
        'dataType' : 'JSON',  # JSON 형식으로 응답 받기
        'base_date' : base_date,
        'base_time' : base_time,
        'nx' : nx, # 예보지점 X 좌표
        'ny' : ny  # 예보지점 Y 좌표
    }

    try:
        # 4. API 호출
        response = requests.get(url, params=params)
        response.raise_for_status() # 오류 발생 시 예외 발생
        
        # 5. 데이터 파싱
        data = response.json()
        
        if data['response']['header']['resultCode'] == '00':
            items = data['response']['body']['items']['item']
            
            print(f"[{base_date} {base_time} 발표] 격자({nx}, {ny}) 예보 정보")
            print("-" * 50)
            
            # 주요 예보 항목 필터링 및 출력
            for item in items:
                fcst_date = item['fcstDate']
                fcst_time = item['fcstTime']
                category = item['category']
                value = item['fcstValue']
                
                # 가이드 문서의 코드값 정보(Category) 활용
                if category == 'TMP':
                    print(f"예보시각: {fcst_date} {fcst_time} | 기온(TMP): {value}℃")
                elif category == 'POP':
                    print(f"예보시각: {fcst_date} {fcst_time} | 강수확률(POP): {value}%")
                elif category == 'SKY':
                    # 하늘상태 코드 변환 (1: 맑음, 3: 구름많음, 4: 흐림)
                    sky_status = {'1': '맑음', '3': '구름많음', '4': '흐림'}
                    print(f"예보시각: {fcst_date} {fcst_time} | 하늘상태(SKY): {sky_status.get(value, value)}")
                    
        else:
            print(f"API 에러 발생: {data['response']['header']['resultMsg']}")
            
    except Exception as e:
        print(f"오류 발생: {e}")

# --- 실행부 ---
# 공공데이터포털에서 발급받은 본인의 인증키를 입력하세요.
MY_SERVICE_KEY = '발급받은_인증키_입력'

# 예보지점 좌표 (예: 서울특별시 종로구 - X: 60, Y: 127)
# 좌표 정보는 별첨 엑셀 자료를 참고해야 합니다.
TARGET_NX = 60
TARGET_NY = 127

get_weather_forecast(MY_SERVICE_KEY, TARGET_NX, TARGET_NY)

반응형

Java

import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.io.BufferedReader;
import java.io.IOException;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class KmaWeatherApi {
    public static void main(String[] args) throws IOException {
        // 1. 공공데이터포털에서 발급받은 인증키
        String serviceKey = "발급받은_인증키_입력"; 
        
        // 2. 요청 파라미터 설정
        String nx = "60";          // 예보지점 X 좌표 (예: 서울) [cite: 450]
        String ny = "127";         // 예보지점 Y 좌표 [cite: 450]
        
        // 현재 날짜와 발표 시각 설정 (단기예보 발표: 0200, 0500, 0800, 1100, 1400, 1700, 2000, 2300) 
        LocalDateTime now = LocalDateTime.now();
        String baseDate = now.format(DateTimeFormatter.ofPattern("yyyyMMdd"));
        String baseTime = "0500"; // 예시: 오전 5시 발표 자료 [cite: 451]

        // 3. URL 빌더를 이용한 요청 주소 생성 [cite: 458]
        StringBuilder urlBuilder = new StringBuilder("http://apis.data.go.kr/1360000/VilageFcstInfoService_2.0/getVilageFcst");
        urlBuilder.append("?" + URLEncoder.encode("serviceKey","UTF-8") + "=" + serviceKey);
        urlBuilder.append("&" + URLEncoder.encode("pageNo","UTF-8") + "=" + URLEncoder.encode("1", "UTF-8"));
        urlBuilder.append("&" + URLEncoder.encode("numOfRows","UTF-8") + "=" + URLEncoder.encode("1000", "UTF-8"));
        urlBuilder.append("&" + URLEncoder.encode("dataType","UTF-8") + "=" + URLEncoder.encode("JSON", "UTF-8"));
        urlBuilder.append("&" + URLEncoder.encode("base_date","UTF-8") + "=" + URLEncoder.encode(baseDate, "UTF-8"));
        urlBuilder.append("&" + URLEncoder.encode("base_time","UTF-8") + "=" + URLEncoder.encode(baseTime, "UTF-8"));
        urlBuilder.append("&" + URLEncoder.encode("nx","UTF-8") + "=" + URLEncoder.encode(nx, "UTF-8"));
        urlBuilder.append("&" + URLEncoder.encode("ny","UTF-8") + "=" + URLEncoder.encode(ny, "UTF-8"));

        // 4. HTTP 연결 및 호출
        URL url = new URL(urlBuilder.toString());
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");
        conn.setRequestProperty("Content-type", "application/json");
        
        System.out.println("Response code: " + conn.getResponseCode());

        // 5. 응답 데이터 읽기
        BufferedReader rd;
        if(conn.getResponseCode() >= 200 && conn.getResponseCode() <= 300) {
            rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));
        } else {
            rd = new BufferedReader(new InputStreamReader(conn.getErrorStream()));
        }
        
        StringBuilder sb = new StringBuilder();
        String line;
        while ((line = rd.readLine()) != null) {
            sb.append(line);
        }
        rd.close();
        conn.disconnect();
        
        // 6. 결과 출력 (실제 프로젝트에서는 JSON Parser 라이브러리로 처리)
        String result = sb.toString();
        System.out.println("결과 데이터:");
        System.out.println(result);
        
        // 7. 강수량 범주 변환 로직 예시 (가이드 문서 내용 적용) 
        // 예보 값(fcstValue)이 float 형태일 때 변환하는 로직입니다.
        // System.out.println("변환된 강수량: " + convertPcp(6.2f));
    }

    /**
     * 가이드 문서에 제시된 강수량(PCP) 범주 변환 로직 [cite: 485-489]
     */
    public static String convertPcp(float f) {
        if(f < 1.0f) return "1mm 미만"; [cite: 486]
        else if(f >= 1.0f && f < 30.0f) return "1.0~29.0mm"; [cite: 487]
        else if(f >= 30.0f && f < 50.0f) return "30.0~50.0mm"; [cite: 488]
        else return "50.0mm이상"; [cite: 489]
    }
}

---

4. 핵심 데이터 및 코드값 정보 (문서 기반)

API 응답에서 category 항목으로 들어오는 코드값의 의미는 다음과 같습니다.

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

 

발표 시각 관련 주의사항 (Base_time)

API는 정해진 시간에만 최신 데이터를 갱신하므로, 호출 시각에 맞춰 base_time을 적절히 설정해야 합니다.

• 단기예보: 0200, 0500, 0800, 1100, 1400, 1700, 2000, 2300 (일 8회)
• 초단기실황: 매시각 정시 (매시 10분 이후 호출 권장)
• 초단기예보: 매시각 30분 발표 (매시 45분 이후 호출 권장)

 

5. 추가 참고사항

• 격자 좌표 (NX, NY): 위경도 좌표를 그대로 사용하는 것이 아니라, 기상청 고유의 격자 좌표로 변환해야 합니다. 가이드 문서에 포함된 C언어 예제 코드를 Python으로 변환하여 사용하거나, 동봉된 엑셀 파일의 행정구역별 좌표 정보를 활용하십시오.
• 데이터 결측: 관측 장비가 없는 지역 등에서는 -900 이상의 값이 missing 값으로 반환될 수 있으니 예외 처리가 필요합니다

기상청41_단기예보 조회서비스_오픈API활용가이드_241128.docx

0.38MB

기상청41_단기예보 조회서비스_오픈API활용가이드_격자_위경도(2510).xlsx

0.66MB