Airkorea Cli

Korean real-time air quality (PM10, PM2.5, O3, NO2, CO, SO2) and 1–3 day forecasts via 한국환경공단 에어코리아 OpenAPI (apis.data.go.kr/B552584). Six subcommands wrap g...

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:

Command	Endpoint	Purpose
scripts/realtime.sh	ArpltnInforInqireSvc/getMsrstnAcctoRltmMesureDnsty	측정소별 실시간/일별/월별 측정값 (1h–90d).
scripts/sido.sh	ArpltnInforInqireSvc/getCtprvnRltmMesureDnsty	시도별 실시간 측정값 (every station in a province).
scripts/forecast.sh	ArpltnInforInqireSvc/getMinuDustFrcstDspth	1~3일 미세먼지/오존 예보.
scripts/station.sh	MsrstnInfoInqireSvc/getMsrstnList	측정소 directory (filter by sido / addr keyword).
scripts/tm.sh	MsrstnInfoInqireSvc/getTMStdrCrdnt	행정/법정동 → TM(중부원점) 좌표.
scripts/nearby.sh	MsrstnInfoInqireSvc/getNearbyMsrstnList	TM 좌표 → 가까운 측정소 목록 (정렬: 거리).

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 <my-동> → nearby --tm-x … --tm-y … → realtime --station <closest> → 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 https://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 < <(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):

Grade	등급	PM2.5 µg/m³	PM10 µg/m³
1	좋음	0–15	0–30
2	보통	16–35	31–80
3	나쁨	36–75	81–150
4	매우나쁨	76+	151+

Errors

AirKorea resultCode	Meaning	This CLI
00	OK	success, JSONL emitted
99 / XML body	등록되지 않은 키 / Decoding key 미사용	exit 22
01	Application error	exit 22
04	HTTP error	exit 22
30	서비스 키 권한 없음	exit 22
12	DEPRECATED OpenAPI	exit 22
33	일일 트래픽 초과	exit 22

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

Composability with other skills in this hub

Pair with	Why
juso-address-cli	Resolve a Korean street address → 행정동 → feed into tm.sh.
kakao-local-cli	Convert WGS84 lat/lng (from a map tap) to TM via Kakao geocoding, then nearby.sh.
kr-holiday-cli	Overlay holiday weekends on AQI charts (commute drops on holidays — visible in NO2).
naver-papago-translate	Localize forecast strings (informCause) for non-KR-speaking users.
tistory-api-cli / velog-cli	Publish a daily AQI digest as a blog post.
kosis-cli	Cross-reference long-run AQI trends with population / industrial-emission stats.

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).