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]