airkorea-cli

intent

wrap Korea's first-party air-quality system (한국환경공단 에어코리아 OpenAPI, operated by the Korea Environment Corporation) to fetch real-time PM10, PM2.5, O3, NO2, CO, SO2 concentrations plus 1, 3 day forecasts, station metadata, and TM-coordinate lookups. use this skill to build AQI dashboards, mask/runner alerts, school outdoor-activity advisories, location-based station queries by 행정동 / 시도 / TM coordinates, or ground LLM answers about Korean air quality in regulator-curated data. data is hourly-granularity, 1, 3 day lag, and 1,000 req/day on the free dev tier.

inputs

required environment variable:

• AIRKOREA_SERVICE_KEY: raw (non-URL-encoded) decoding key from data.go.kr registration. register at https://www.data.go.kr/, apply for both services (auto-approved dev tier): "한국환경공단_에어코리아_대기오염정보" (real-time + forecast) and "한국환경공단_에어코리아_측정소정보" (station directory + TM utilities). copy the Decoding key (not Encoded) from your registered app dashboard.

optional environment variables:

• ARPLTN_BASE: override default base URL https://apis.data.go.kr/B552584/ArpltnInforInqireSvc for real-time/forecast endpoints.
• MSRSTN_BASE: override default base URL https://apis.data.go.kr/B552584/MsrstnInfoInqireSvc for station info/TM endpoints.

external integrations (optional pairs):

• juso-address-cli: resolve Korean street addresses to 행정동 names before feeding into tm.sh.
• kakao-local-cli: convert WGS84 lat/lng to TM coordinates, then pass to nearby.sh.
• kr-holiday-cli: overlay holidays on AQI time-series (NO2 drops on holidays due to reduced commute).
• naver-papago-translate: localize forecast text (informCause) for non-Korean-speaking end-users.
• tistory-api-cli or velog-cli: publish daily AQI digests as blog posts.

rate limits and quotas:

• dev tier: 1,000 requests/day per service (two separate limits: one for ArpltnInforInqireSvc, one for MsrstnInfoInqireSvc).
• production tier: higher limits, apply via data.go.kr for commercial/high-volume use.
• AirKorea publishes hourly (with ~1h publication delay); sub-hourly queries return the same record.

procedure

1. register and retrieve key

   • input: korean SSN or business registration, email.
   • go to https://www.data.go.kr/, create an account (free, no business required).
   • search for "한국환경공단_에어코리아_대기오염정보" and "한국환경공단_에어코리아_측정소정보", apply for both.
   • navigate to "내 API" (my APIs) dashboard, find your registered app, click "상세보기" (details).
   • copy the Decoding key (행정망 button or the raw unhashed form, not the URL-encoded version).
   • output: AIRKOREA_SERVICE_KEY ready for export.

2. set environment and validate connectivity

   • input: AIRKOREA_SERVICE_KEY, ARPLTN_BASE and MSRSTN_BASE (optional).
   • run export AIRKOREA_SERVICE_KEY='<your_decoded_key>'.
   • optionally export base URL overrides if using a proxy or alternate endpoint.
   • output: shell environment ready; credentials verified on first API call.

3. query real-time measurements by station

   • input: station name (e.g., "강남구"), period (HOUR, DAY, MONTH, 3MONTH for 1h/1d/1mo/90d), optional record limit.
   • command: scripts/realtime.sh --station <name> --period <HOUR|DAY|MONTH|3MONTH> --num <limit>.
   • output: JSONL, one row per measurement record, fields: dataTime, stationName, mangName, so2Value, coValue, o3Value, no2Value, pm10Value, pm25Value, khaiValue, and grade fields (khaiGrade, so2Grade, coGrade, o3Grade, no2Grade, pm10Grade, pm25Grade).

4. query real-time measurements by province (시도)

   • input: province name (e.g., "서울", "전국" for nationwide), optional record limit.
   • command: scripts/sido.sh --sido <name> --num <limit>.
   • output: JSONL, one row per station in that province, same schema as realtime.sh.

5. query 1, 3 day air-quality forecasts

   • input: date (YYYY-MM-DD, today or future), optional pollutant code (PM25 or O3; omit for all).
   • command: scripts/forecast.sh --date <YYYY-MM-DD> [--code <PM25|O3>].
   • output: JSONL, one row per forecast, fields: informDate, informCode (PM25 or O3), informGrade (1, 4), informCause (korean text describing forecast reason).

6. fetch station directory and filter

   • input: optional filter (sido name, address keyword).
   • command: scripts/station.sh [--sido <name>] [--keyword <search>].
   • output: JSONL, one row per station, fields: stationName, sidoName, districtName, mangName (measurement type), tmX, tmY (TM coordinates), addr (korean address).

7. convert 행정동 (administrative dong) to TM coordinates

   • input: 행정동 name (e.g., "역삼동", "강남구").
   • command: scripts/tm.sh --umd <dong_name>.
   • output: JSONL, one row per match, fields: sidoName, cityName, districtName, tmX, tmY.

8. find nearby stations from TM coordinates

   • input: TM X and Y coordinates (from step 7 or kakao-local-cli).
   • command: scripts/nearby.sh --tm-x <x> --tm-y <y>.
   • output: JSONL, sorted by distance (nearest first), fields: stationName, distance (km), tmX, tmY, sidoName.

9. pipe output to jq, csvkit, or downstream skills

   • input: JSONL output from any of steps 3, 8.
   • filter with jq -c 'select(.pm25Grade == "4")' to find bad-air stations.
   • convert to CSV with jq -r '[.dataTime, .pm10Value, .pm25Value] | @csv'.
   • feed to naver-papago-translate to localize forecast text for non-KR users.
   • output: filtered, formatted, or localized data ready for dashboards, alerts, or digests.

decision points

if AIRKOREA_SERVICE_KEY is missing or invalid:

• exit code 22 (EINVAL). error message includes "SERVICE_KEY_IS_NOT_REGISTERED_ERROR" or "Decoding key 미사용".
• action: re-check that you pasted the Decoding key, not the Encoded key. re-export and retry.

if request returns resultCode 33 (daily traffic limit exceeded):

• exit code 22. error message: "일일 트래픽 초과".
• action: wait until next UTC day (data.go.kr resets at 00:00 UTC). if you need higher throughput, apply for production tier.

if request returns resultCode 30 (no service permission):

• exit code 22. error message: "서비스 키 권한 없음".
• action: log in to data.go.kr, confirm both services are registered (not declined or pending). reapply if expired.

if resultCode 99, 01, 04, or 12 (malformed key, app error, HTTP error, deprecated API):

• exit code 22. error message includes resultCode and XML errMsg.
• action: verify AIRKOREA_SERVICE_KEY format (should be ~30 alphanumeric chars). confirm endpoint URLs are current (check data.go.kr API docs). restart the cli after fixing the key.

if a station query returns empty result set:

• exit code 0, JSONL output is empty (zero lines).
• action: widen the search (different station name, different province). use scripts/station.sh to list all valid station names in your region.

if --period 3MONTH returns fewer than expected rows:

• data older than 90 days may be archived or deleted by AirKorea. exit code 0 (success), but row count is low.
• action: confirm the station existed 90 days ago. check kr-holiday-cli or AirKorea's maintenance windows.

if TM coordinates are out of valid range (e.g., outside Korean territory):

• nearby.sh returns empty or error (resultCode 01).
• action: validate your TM-X and TM-Y bounds (TM standard origin is in the middle of Korea; typical values 200k, 500k for both). use kakao-local-cli or tm.sh to regenerate coordinates.

if you need data before 1h ago:

• AirKorea has ~1h publication delay. queries for the current hour return the prior hour's data.
• action: no workaround. for minute-level or sub-hourly data, use IoT vendor APIs (Awair, IQAir).

output contract

all commands emit JSONL (one JSON object per line, no array wrapping). piping works directly with jq, csvkit, pandas, or downstream Implexa skills.

realtime.sh schema:

{
  "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 (1, 4):

sido.sh schema: same as realtime.sh, multiple stations per province.

forecast.sh schema:

{
  "informDate": "2026-04-29",
  "informCode": "PM25",
  "informGrade": "2",
  "informCause": "현재 대기 상태는 보통이며, 자동차 배기가스 등의 영향으로 내일 일부 지역에서 미세먼지가 높을 것으로 예상됩니다."
}

station.sh schema:

{
  "stationName": "강남구",
  "sidoName": "서울",
  "districtName": "강남구",
  "mangName": "도시대기",
  "tmX": "328000.0",
  "tmY": "553000.0",
  "addr": "서울특별시 강남구 테헤란로 xxx"
}

tm.sh schema:

{
  "sidoName": "서울",
  "cityName": "강남구",
  "districtName": "역삼동",
  "tmX": "328100.5",
  "tmY": "553050.3"
}

nearby.sh schema (sorted by distance, nearest first):

{
  "stationName": "강남구",
  "distance": "1.2",
  "tmX": "328000.0",
  "tmY": "553000.0",
  "sidoName": "서울"
}

file locations: output goes to stdout; no files written unless piped (> file.jsonl).

outcome signal

• success: exit code 0, JSONL emitted to stdout with at least one record. each record is parseable by jq and contains expected fields (no null errors, no XML error payloads).
• jq validation: run jq empty on output; if it succeeds, schema is valid.
• in a dashboard: real-time station snapshot updates every 10, 60 minutes (cache hourly). forecast row appears 1, 3 days ahead with informGrade and informCause visible to staff/parents.
• in an alert: run scripts/sido.sh --sido 전국 --num 1000 | jq -c 'select(.pm25Grade == "4")' and confirm one row per "매우나쁨" station; fire notification to runners/schools if count > 0.
• in an LLM ground-truth check: feed a real-time station record into your answer builder; if the station's name, dataTime, and pm25Grade match the API response, the citation is live and verified.
• error outcome: exit code 22 (EINVAL) or non-zero means auth failure, rate limit, missing service permission, or invalid parameters. check stderr for resultCode and errMsg; fix the key or wait for rate-limit reset.