AI Knowledge Hub기상청 단기예보 조회서비스
초단기실황·초단기예보·단기예보·예보버전을 조회하는 기상청 공식 OpenAPI. 전국을 5km×5km 격자로 나누어 읍면동 단위 날씨를 제공한다.
에이전트가 얻을 수 있는 정보
- 기온(TMP), 하늘상태(SKY), 강수형태(PTY), 강수확률(POP), 강수량(PCP), 습도(REH), 풍속(WSD), 최고·최저기온(TMX/TMN), 1시간 단위 예보
날씨 기반 의사결정, 일정 제안, 야외활동·배달·농업 최적화
활용 사례
- 오늘·내일 날씨 질의응답
- 지역별 강수확률 비교
- 야외 활동 스케줄링
- 날씨 기반 상품·콘텐츠 추천
등록 API (4)
초단기실황 조회 getUltraSrtNcst
관측소 대표값 기반 실황. 발표 후 1시간 내
base_date필수 — 발표일자 YYYYMMDD 예:20261010base_time필수 — 발표시각 HHMM 정시 예:0600nx필수 — 예보지점 X 좌표 예:55ny필수 — 예보지점 Y 좌표 예:127pageNo옵션 예:1numOfRows옵션 예:1000dataType옵션 예:JSON
출력: category (자료구분코드: T1H 기온, UUU/VVV 바람, WSD 풍속, RN1 강수량, REH 습도, PTY 강수형태), obsrValue (실황값), baseDate, baseTime, nx, ny
호출 한도: 일 10,000회 (개발계정 기준. 운영계정은 활용사례 등록 후 증설 가능)
초단기예보 조회 getUltraFcst
예보시점부터 6시간까지 1시간 단위
base_date필수 예:20261010base_time필수 — 정시+30분 단위 예:0630nx필수ny필수pageNo옵션numOfRows옵션dataType옵션
출력: PTY(강수형태), PY(강수확률), PCP(강수량), REH(습도), TMP(기온), VEC(풍향), WSD(풍속), fcstTime, fcstDate
호출 한도: 일 10,000회
단기예보 조회 getVilageFcst
3시간 간격, 글피까지 확장. 가장 많이 쓰이는 엔드포인트
base_date필수 예:20261010base_time필수 — 0200/0500/0800/1100/1400/1700/2000/2300 예:0500nx필수ny필수pageNo옵션numOfRows옵션dataType옵션
출력: POP(강수확률), PTY(강수형태), PCP(강수량), REH(습도), SNO(적설), SKY(하늘상태), TMP(기온), TMN(최저), TMX(최고), WSD(풍속)
호출 한도: 일 10,000회
예보버전 조회 getVersion
제공 데이터 버전 확인
pageNo옵션numOfRows옵션dataType옵션
출력: stnIds, code, availableTime
호출 한도: 일 10,000회
인증·비용·약관
| 인증 방식 | ServiceKey — data.go.kr 인증키. 프록시 서버에만 보관하며 에이전트에게 노출하지 않는다. 에이전트는 X-Agent-Token으로 우리 프록시만 호출한다. |
|---|---|
| 비용 | 무료. 개발·운영 모두 자동승인 |
| 이용허락 | 공공저작물: 출처표시(제1유형) + 저작자표시(CC BY) |
| 재배포 | 허용 (출처표시 필수) |
| 약관 확인일 | 2026-10-10 |
| 활용신청 | 포털 로그인 → 기상청_단기예보 조회서비스 활용신청 → 인증키 발급 (자동승인) 포털 바로가기 |
| 운영 상태 | active |
| 최종 확인일 | 2026-10-10 |
에이전트 호출 방법
우리 프록시를 통해 호출합니다. 헤더 X-Agent-Token이 필요합니다.
예시: POST /agencatalog/api/call {service:'kma-vilage-fcst', endpoint:'getVilageFcst', params:{base_date,base_time,nx,ny}}
기계용 JSON 스키마
{
"service": "kma-vilage-fcst",
"name": "기상청 단기예보 조회서비스",
"provider": "기상청",
"apis": [
{
"id": "getUltraSrtNcst",
"name": "초단기실황 조회",
"params": [
{
"name": "base_date",
"required": true,
"example": "20261010",
"desc": "발표일자 YYYYMMDD"
},
{
"name": "base_time",
"required": true,
"example": "0600",
"desc": "발표시각 HHMM 정시"
},
{
"name": "nx",
"required": true,
"example": "55",
"desc": "예보지점 X 좌표"
},
{
"name": "ny",
"required": true,
"example": "127",
"desc": "예보지점 Y 좌표"
},
{
"name": "pageNo",
"required": false,
"example": "1"
},
{
"name": "numOfRows",
"required": false,
"example": "1000"
},
{
"name": "dataType",
"required": false,
"example": "JSON"
}
]
},
{
"id": "getUltraFcst",
"name": "초단기예보 조회",
"params": [
{
"name": "base_date",
"required": true,
"example": "20261010"
},
{
"name": "base_time",
"required": true,
"example": "0630",
"desc": "정시+30분 단위"
},
{
"name": "nx",
"required": true
},
{
"name": "ny",
"required": true
},
{
"name": "pageNo",
"required": false
},
{
"name": "numOfRows",
"required": false
},
{
"name": "dataType",
"required": false
}
]
},
{
"id": "getVilageFcst",
"name": "단기예보 조회",
"params": [
{
"name": "base_date",
"required": true,
"example": "20261010"
},
{
"name": "base_time",
"required": true,
"example": "0500",
"desc": "0200/0500/0800/1100/1400/1700/2000/2300"
},
{
"name": "nx",
"required": true
},
{
"name": "ny",
"required": true
},
{
"name": "pageNo",
"required": false
},
{
"name": "numOfRows",
"required": false
},
{
"name": "dataType",
"required": false
}
]
},
{
"id": "getVersion",
"name": "예보버전 조회",
"params": [
{
"name": "pageNo",
"required": false
},
{
"name": "numOfRows",
"required": false
},
{
"name": "dataType",
"required": false
}
]
}
],
"proxy_call": "POST /agencatalog/api/call",
"attribution": "출처: 기상청 단기예보 조회서비스(공공데이터포털 data.go.kr)"
}
이용 시 주의사항
- 기관 API 키는 서버에만 보관됩니다. 직접 키를 요청하는 클라이언트는 이 경로를 사용할 수 없습니다.
- 기관별 일일 한도가 있습니다. 한도 초과 시 429를 반환하고 추가 호출을 차단합니다.
- 기관 API 장애·한도 초과 시 오류가 전달됩니다. 재시도 전에 응답의 error 필드를 확인하세요.
- 출처 표기: 출처: 기상청 단기예보 조회서비스(공공데이터포털 data.go.kr)
마지막 확인: 2026-10-10