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:

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

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: bash

   export AIRKOREA_SERVICE_KEY='your_decoded_key_here'
   
   

4. Optional overrides (rarely needed): bash

   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#

bash

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

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

bash

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#

bash

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

D) 90-day station history → CSV#

bash

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#

bash

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

json

{
  "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–150–302보통16–3531–803나쁨36–7581–1504매우나쁨76+151+

Errors#

AirKorea resultCodeMeaningThis CLI00OKsuccess, JSONL emitted99 / XML body등록되지 않은 키 / Decoding key 미사용exit 2201Application errorexit 2204HTTP errorexit 2230서비스 키 권한 없음exit 2212DEPRECATED OpenAPIexit 2233일일 트래픽 초과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 withWhyjuso-address-cliResolve a Korean street address → 행정동 → feed into tm.sh.kakao-local-cliConvert WGS84 lat/lng (from a map tap) to TM via Kakao geocoding, then nearby.sh.kr-holiday-cliOverlay holiday weekends on AQI charts (commute drops on holidays — visible in NO2).naver-papago-translateLocalize forecast strings ( informCause) for non-KR-speaking users.tistory-api-cli / velog-cliPublish a daily AQI digest as a blog post.kosis-cliCross-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).