기상청 초단기 실황 응답을 관측 시각·격자 좌표·주요 기상 값 중심으로 정규화합니다.

기상청 단기예보

복잡한 data.go.kr envelope과 카테고리 코드를 평탄화해 즉시 활용 가능한 날씨 객체로 제공합니다.

엔드포인트

GET /v1/kma-short-forecast

Upstream

Base URL: https://apis.data.go.kr/1360000/VilageFcstInfoService_2.0
Path: /getUltraSrtNcst

요청 파라미터

파라미터	타입	필수	기본값	설명
`gridX`	integer	✅	-	예보지점 X 격자 좌표 (nx)
`gridY`	integer	✅	-	예보지점 Y 격자 좌표 (ny)
`baseDate`	string	❌	-	기준일 (YYYYMMDD, 기본: 오늘)
`baseTime`	string	❌	-	기준 시각 (HHmm, 기본: 현재 정시)

요청 예시

{
  "gridX": 60,
  "gridY": 127,
  "baseDate": "20250322",
  "baseTime": "1400"
}

응답 스키마

아래 스키마는 adapter의 Zod output schema에서 직접 생성됩니다.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "observedAt": {
      "type": "string",
      "description": "관측 시각 (ISO 8601 KST)"
    },
    "grid": {
      "type": "object",
      "properties": {
        "x": {
          "type": "number"
        },
        "y": {
          "type": "number"
        }
      },
      "required": [
        "x",
        "y"
      ],
      "additionalProperties": false
    },
    "temperature": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "기온 (°C)"
    },
    "humidity": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "습도 (%)"
    },
    "windSpeed": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "풍속 (m/s)"
    },
    "precipitation1h": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "description": "1시간 강수량 (mm), 강수없음→null"
    },
    "precipitationType": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "강수형태 (none/rain/sleet/snow)"
    },
    "sky": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "하늘 상태 (clear/mostly_cloudy/overcast)"
    }
  },
  "required": [
    "observedAt",
    "grid",
    "temperature",
    "humidity",
    "windSpeed",
    "precipitation1h",
    "precipitationType",
    "sky"
  ],
  "additionalProperties": false
}

응답 예시

{
  "data": {
    "observedAt": "2025-03-22T14:00:00+09:00",
    "grid": {
      "x": 60,
      "y": 127
    },
    "temperature": 18.4,
    "humidity": 38,
    "windSpeed": 2.1,
    "precipitation1h": null,
    "precipitationType": "none",
    "sky": "clear"
  },
  "pagination": null,
  "meta": {
    "source": "kma-short-forecast",
    "fetchedAt": "2026-03-24T00:00:00.000Z"
  }
}

정규화 사항

response.body.items.item envelope을 언랩하고 category 코드를 pivot 형태로 합칩니다.
T1H/REH/WSD를 숫자 필드로 변환하고 RN1의 한국어 null 패턴을 null로 치환합니다.
PTY/SKY 코드를 none/rain/sleet/snow 및 clear/mostly_cloudy/overcast enum으로 매핑합니다.
baseDate/baseTime을 ISO 8601 KST observedAt 값으로 변환합니다.

기상청 단기예보

On this page