Kma Weather

kma-weather

Get official weather information from Korea Meteorological Administration (KMA) 기상청.

Features

• Current Weather - Real-time observations (temperature, humidity, precipitation, wind)
• Short-term Forecast - Ultra-short (6 hours) and short-term (3 days) forecasts
• Mid-term Forecast - 3-10 day outlook
• Weather Warnings - Official warnings (typhoon, heavy rain, snow, etc.)
• High Resolution - 5km×5km grid system for precise local forecasts

Quick Start

# Get current weather + 6-hour forecast (brief)
python3 skills/kma-weather/scripts/forecast.py brief --lat 37.5665 --lon 126.9780

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

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

# Get current nationwide weather warnings status
python3 skills/kma-weather/scripts/weather_warnings.py

# Get mid-term forecast for Seoul
python3 skills/kma-weather/scripts/midterm.py --region 서울

Setup

1. Get API Key

1. Visit 공공데이터포털
2. Sign up / Log in
3. Request access to these 3 APIs (all use the same key):
   • 기상청 단기예보 조회서비스 (15084084)
   • 기상청 기상특보 조회서비스 (15000415)
   • 기상청 중기예보 조회서비스 (15059468)
4. Wait for approval (usually instant to 1 day, auto-approved)
5. Go to My Page → API Key Management
6. Copy your ServiceKey

Note: All 3 APIs use the same API key.

2. Set Environment Variable

Add your API key to the environment:

For Sandbox (Docker/Podman):

# In agents.yaml
agents:
  defaults:
    sandbox:
      docker:
        env:
          KMA_SERVICE_KEY: "your-service-key-here"

For Host:

# In agents.yaml
agents:
  defaults:
    env:
      vars:
        KMA_SERVICE_KEY: "your-service-key-here"

Or export directly:

export KMA_SERVICE_KEY="your-service-key-here"

Usage

Current Weather

Get real-time weather observations:

python3 skills/kma-weather/scripts/forecast.py current \
  --lat 37.5665 --lon 126.9780

Output:

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

Short-term Forecast

Ultra-short forecast (6 hours):

python3 skills/kma-weather/scripts/forecast.py ultrashort \
  --lat 37.5665 --lon 126.9780

Short-term forecast (3 days):

# 내일 예보 (기본값)
python3 skills/kma-weather/scripts/forecast.py shortterm \
  --lat 37.5665 --lon 126.9780

# 모레 예보
python3 skills/kma-weather/scripts/forecast.py shortterm \
  --lat 37.5665 --lon 126.9780 --days 2

# 글피 예보
python3 skills/kma-weather/scripts/forecast.py shortterm \
  --lat 37.5665 --lon 126.9780 --days 3

# 모든 예보 데이터 (3일치 전체)
python3 skills/kma-weather/scripts/forecast.py shortterm \
  --lat 37.5665 --lon 126.9780 --days all

**--days Options **: all=전체, 1=내일(기본), 2=모레, 3=글피

Combined Forecasts

Brief (current + 6 hours) - Perfect for quick weather checks:

python3 skills/kma-weather/scripts/forecast.py brief \
  --lat 37.5665 --lon 126.9780

All (current + ultrashort + shortterm) - Full data:

python3 skills/kma-weather/scripts/forecast.py all \
  --lat 37.5665 --lon 126.9780

When outputting JSON, return a structure separated by type:

python3 skills/kma-weather/scripts/forecast.py brief --lat 37.5665 --lon 126.9780 --json
# {"current": {...}, "ultrashort": {...}}

python3 skills/kma-weather/scripts/forecast.py all --lat 37.5665 --lon 126.9780 --json
# {"current": {...}, "ultrashort": {...}, "shortterm": {...}}

Weather Warnings

Check current nationwide weather warning status:

# Get current nationwide warning status
python3 skills/kma-weather/scripts/weather_warnings.py

Output:

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

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

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

Mid-term Forecast

Get 3-10 day forecasts by region:

# By region name
python3 skills/kma-weather/scripts/midterm.py --region 서울

# By station code
python3 skills/kma-weather/scripts/midterm.py --stn-id 109

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

Raw JSON Output

All scripts support --json flag for raw API responses:

python3 skills/kma-weather/scripts/forecast.py current \
  --lat 37.5665 --lon 126.9780 --json

Grid Coordinates

KMA uses a 5km×5km grid system based on Lambert Conformal Conic projection.

Convert lat/lon to grid coordinates:

python3 skills/kma-weather/scripts/grid_converter.py 37.5665 126.9780

Output:

Input: (37.5665, 126.9780)
Grid:  (60, 127)
Verify: (37.5665, 126.9780)

The scripts automatically handle grid conversion, so you can use latitude/longitude directly.

Using in Python Code

Import and use functions directly:

from skills.kma_weather.scripts.forecast import fetch_forecast, format_current
from skills.kma_weather.scripts.grid_converter import latlon_to_grid

# Get current weather
data = fetch_forecast("current", lat=37.5665, lon=126.9780)
print(format_current(data))

# Convert coordinates
nx, ny = latlon_to_grid(37.5665, 126.9780)
print(f"Grid: ({nx}, {ny})")

API Details

For detailed API documentation, see:

• [references/api-forecast.md] - Short-term forecast API
• [references/api-warnings.md] - Weather warnings API
• [references/api-midterm.md] - Mid-term forecast API
• [references/category-codes.md] - Category code reference

Workflow Examples

See [examples/daily-check.md] for a complete daily weather check workflow.

Notes

• API Release Schedule:
  • Current/ultra-short: Every hour at :10 minutes
  • 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)
• Grid Resolution: 5km×5km (higher resolution than global services)
• Coverage: South Korea only
• API Limits: Check 공공데이터포털 for your plan's rate limits
• Auto-pagination: Script automatically fetches all pages when data exceeds single page limit (300 rows/page)

Comparison: weather vs kma-weather

Recommendation: Use both skills complementarily:

• weather for global locations
• kma-weather for detailed Korean forecasts and weather warnings

Troubleshooting

"KMA API service key not found"

Set the KMA_SERVICE_KEY environment variable. See Setup.

"API Error 30: SERVICE_KEY_IS_NOT_REGISTERED_ERROR"

Your API key is invalid or not approved yet. Check:

1. Did you request access to all 3 KMA APIs?
2. Has your request been approved?
3. Is the key copied correctly (no extra spaces)?

"API Error 22: SERVICE_TIMEOUT_ERROR"

The KMA API server is experiencing delays. Try again in a few moments.

No data returned

• Check if the coordinates are within South Korea.
• Verify the grid coordinates using grid_converter.py.
• Try increasing --rows parameter (default: 300). If it's too high, you may receive a 429 too many requests error.

License

This skill uses public APIs from the Korea Meteorological Administration via 공공데이터포털.

Implementation Status

This skill implements the most commonly used endpoints. Additional endpoints may be added in future versions based on needs.

For more details, please read [implement-status.md]