kma-weather

Quick Start

# Current weather + 6-hour forecast
python3 skills/kma-weather/scripts/forecast.py brief --lat 37.5665 --lon 126.9780

# All forecasts as JSON (current + ultrashort + shortterm)
python3 skills/kma-weather/scripts/forecast.py all --lat 37.5665 --lon 126.9780 --json

# Short-term forecast (3 days)
python3 skills/kma-weather/scripts/forecast.py shortterm --lat 37.5665 --lon 126.9780 --days all

# Nationwide weather warnings/advisories (기상특보)
python3 skills/kma-weather/scripts/weather_warnings.py

# Mid-term forecast (3-10 days)
python3 skills/kma-weather/scripts/midterm.py --region 서울

Setup

1. Get API Key

1. Visit 공공데이터포털
2. Request access to these 3 APIs (all use the same key):
   • 기상청 단기예보 조회서비스 (15084084)
   • 기상청 기상특보 조회서비스 (15000415)
   • 기상청 중기예보 조회서비스 (15059468)
3. Copy your ServiceKey from My Page → API Key Management

2. Set Environment Variable

In ~/.openclaw/openclaw.json:

Sandbox (add to agents.defaults.sandbox.docker.env):

{
  "agents": {
    "defaults": {
      "sandbox": {
        "docker": {
          "env": {
            "KMA_SERVICE_KEY": "your-key"
          }
        }
      }
    }
  }
}

Host (add to env.vars):

{
  "env": {
    "vars": {
      "KMA_SERVICE_KEY": "your-key"
    }
  }
}

Usage

forecast.py

Command	Description
current	Real-time observations
ultrashort	6-hour forecast
shortterm	3-day forecast
brief	current + ultrashort
all	current + ultrashort + shortterm

Options:

• --lat, --lon: Coordinates (required)
• --days: For shortterm - 1 (tomorrow, default), 2, 3, or all
• --json: Raw JSON output

Output example (current):

🌤️ 현재 날씨 (초단기실황)
🌡️  기온: 5.2°C
💧 습도: 65%
🌧️  강수량: 0mm (1시간)
💨 풍속: 2.3m/s
🧭 풍향: NW (315°)

weather_warnings.py

Returns current nationwide 기상특보:

🚨 기상특보 현황
발표시각: 2026-02-01 10:00
발효시각: 2026-02-01 10:00

📍 현재 발효 중인 특보
  • 건조경보 : 강원도, 경상북도, ...
  • 풍랑주의보 : 동해중부안쪽먼바다, ...

⚠️  예비특보
  • (1) 강풍 예비특보 : 02월 02일 새벽(00시~06시) : 울릉도.독도

midterm.py

3-10 day forecast by region.

python3 skills/kma-weather/scripts/midterm.py --region 서울
python3 skills/kma-weather/scripts/midterm.py --stn-id 109

Regions: 서울, 인천, 경기, 부산, 대구, 광주, 대전, 울산, 세종, 강원, 충북, 충남, 전북, 전남, 경북, 경남, 제주

grid_converter.py

Convert lat/lon to KMA 5km grid (auto-handled by other scripts):

python3 skills/kma-weather/scripts/grid_converter.py 37.5665 126.9780
# Output: Grid: (60, 127)

API Notes

• Release Schedule:
  • Current: Every hour at :40 (base_time: HH00)
  • Ultra-short: Every hour at :45 (base_time: HH30)
  • Short-term: 02:10, 05:10, 08:10, 11:10, 14:10, 17:10, 20:10, 23:10 (KST)
  • Mid-term: 06:00, 18:00 (KST)
• Coverage: South Korea only
• Auto-pagination: Scripts fetch all pages automatically

vs weather skill

	weather	kma-weather
Coverage	Global	Korea only
API Key	No	Required
Resolution	City-level	5km grid
Weather Warnings	No	Yes (기상특보)

Use both: weather for global, kma-weather for detailed Korean forecasts and 기상특보.

Troubleshooting

Error	Solution
KMA API service key not found	Set KMA_SERVICE_KEY env var
SERVICE_KEY_IS_NOT_REGISTERED_ERROR	Check API approval status, verify key
SERVICE_TIMEOUT_ERROR	Retry later
No data returned	Verify coordinates are in South Korea

References (Raw API Documentation)

• references/api-forecast.md - 단기예보 API endpoints, parameters, response format
• references/api-warnings.md - 기상특보 API endpoints, parameters, response format
• references/api-midterm.md - 중기예보 API endpoints, parameters, response format
• references/category-codes.md - KMA category codes (SKY, PTY, etc.)
• implement-status.md - Implementation status