airkorea-cli

Command-line wrapper for 한국환경공단 에어코리아 OpenAPI — Korea's first-party air-quality system. Operated by the Korea Environment Corporation, it is the data behind airkorea.or.kr, every weather-app AQI badge in Korea, and the 미세먼지 alert that pings 50M phones on bad-haze days.

Six subcommands wrap two services:

All output is JSONL — one row per record — so it pipes directly into jq, csvkit, pandas, or downstream skills.

When to use this skill

• AQI dashboards — sido --sido 전국 --num 600 to get a country-wide snapshot in one call; cache hourly.
• Location-based mask/runner alerts — tm --umd \x3Cmy-동> → nearby --tm-x … --tm-y … → realtime --station \x3Cclosest> → push notification when pm25Grade ≥ 3.
• School outdoor-activity advisories — schedule forecast --date $(date +%F) daily; surface informGrade and informCause to staff/parents.
• Korean-news AQI grounding — when an LLM answers "오늘 강남 미세먼지 어때?", cite real-time station data, not hallucinated numbers.
• Backfill / research panels — realtime --period 3MONTH to pull the last 90 days for any single station; combine with kr-holiday-cli to test holiday-traffic effects.

Do not use this skill for

• Sub-hourly or sensor-grade data — AirKorea publishes at hourly granularity (with a ~1h delay). For minute-level, use IoT vendors (Awair, IQAir partnerships).
• Outside-Korea AQI — only 한국환경공단 stations. For other countries, use OpenAQ, AirNow, or WAQI.
• Health-effect interpretations — the API returns concentrations + grades, not personalized health advice. Pair with WHO/CDC guidance text on the consumer side.
• High-throughput public-facing apps without a prod-tier key — dev-tier ceiling is 1,000 req/day per service. Apply for production tier on data.go.kr.

Prerequisites

1. Register at \x3Chttps://www.data.go.kr/> (Korean OpenData portal, free, no business required).
2. Apply for both services (auto-approved for the dev tier):
   • "한국환경공단_에어코리아_대기오염정보" (real-time + forecast)
   • "한국환경공단_에어코리아_측정소정보" (station directory + TM utilities)
3. Copy the Decoding key (the raw form, not URL-encoded) and export:

   export AIRKOREA_SERVICE_KEY='your_decoded_key_here'
   

4. Optional overrides (rarely needed):

   export ARPLTN_BASE='https://apis.data.go.kr/B552584/ArpltnInforInqireSvc'
   export MSRSTN_BASE='https://apis.data.go.kr/B552584/MsrstnInfoInqireSvc'
   

Common workflows

A) Snapshot every Seoul station right now

scripts/sido.sh --sido 서울 --num 60 \
  | jq -c '{stationName, dataTime, pm10Value, pm25Value, pm10Grade, pm25Grade}'

B) Find my closest station from a 동 name (full chain)

read TMX TMY \x3C \x3C(scripts/tm.sh --umd 역삼동 \
  | jq -r 'select(.sidoName=="서울") | "\(.tmX) \(.tmY)"' | head -1)

scripts/nearby.sh --tm-x "$TMX" --tm-y "$TMY" | head -3
# → e.g. "강남구", distance ~1.2km

scripts/realtime.sh --station 강남구 --period HOUR --num 1 \
  | jq -c '{dataTime, pm25Value, pm25Grade, pm10Value, pm10Grade, o3Value, no2Value}'

C) Daily forecast headline for a digest email

scripts/forecast.sh --date "$(date +%F)" --code PM25 \
  | jq -r '"\(.informData) (\(.informCode)) — \(.informGrade // "-")"'

D) 90-day station history → CSV

scripts/realtime.sh --station 종로구 --period 3MONTH --num 1000 \
  | jq -r '[.dataTime, .pm10Value, .pm25Value, .o3Value, .no2Value] | @csv' \
  > jongno_90d.csv

E) Run a "very-bad" alert across the country

scripts/sido.sh --sido 전국 --num 1000 \
  | jq -c 'select((.pm25Grade // "-") == "4")'
# emit one row per station that's in 매우나쁨 right now → fan out to your alerter

Output shape — sample (realtime.sh)

{
  "dataTime": "2026-04-29 09:00",
  "stationName": "강남구",
  "mangName": "도시대기",
  "so2Value": "0.003",
  "coValue": "0.4",
  "o3Value": "0.041",
  "no2Value": "0.018",
  "pm10Value": "47",
  "pm25Value": "22",
  "khaiValue": "78",
  "khaiGrade": "2",
  "so2Grade": "1",
  "coGrade": "1",
  "o3Grade": "1",
  "no2Grade": "1",
  "pm10Grade": "1",
  "pm25Grade": "2"
}

Grade encoding (used by every *Grade field):

Errors

If you get an XML payload with \x3CerrMsg>SERVICE_KEY_IS_NOT_REGISTERED_ERROR\x3C/errMsg>, you most likely pasted the Encoded key — switch to the Decoding version on data.go.kr.

Composability with other skills in this hub

License

MIT — see LICENSE. AirKorea data is © 한국환경공단; redistribution is permitted under the data.go.kr open-data terms (https://www.data.go.kr/ugs/selectPortalPolicyView.do).