📦 Airkorea Cli — Airkorea CLI

airkorea-cli 命令行封装 한국환경공단 에어코리아 OpenAPI——韩国官方空气质量系统。由韩国环境公社运营，为 airkorea.or.kr、韩国所有天气 App 的 AQI 徽章及雾霾日推送 5000 万手机的 미세먼지 警报提供数据。六个子命令封装两项服务：

• scripts/realtime.sh ArpltnInforInqireSvc/getMsrstnAcctoRltmMesureDnsty 站点实时/日/月数据（1h–90d）。
• scripts/sido.sh ArpltnInforInqireSvc/getCtprvnRltmMesureDnsty 按 시도 实时数据（省内全部站点）。
• scripts/forecast.sh ArpltnInforInqireSvc/getMinuDustFrcstDspth 1–3 天 미세먼지/오존 预报。
• scripts/station.sh MsrstnInfoInqireSvc/getMsrstnList 站点目录（按 시도/地址关键词过滤）。
• scripts/tm.sh MsrstnInfoInqireSvc/getTMStdrCrdnt 行政/法定洞 → TM(중부원점) 坐标。
• scripts/nearby.sh MsrstnInfoInqireSvc/getNearbyMsrstnList TM 坐标 → 最近站点列表（按距离排序）。

全部输出 JSONL，每行一条记录，可直接 pipe 给 jq、csvkit、pandas 或下游技能。

使用场景

• AQI 看板：sido --sido 전국 --num 600 一键获取全国快照；每小时缓存。
• 基于位置的口罩/跑步提醒：tm --umd → nearby --tm-x … --tm-y … → realtime --station <最近站>，pm25Grade ≥ 3 时推送。
• 学校户外活动建议：每日定时 forecast --date $(date +%F)，将 informGrade、informCause 推送给教职工/家长。
• 韩媒 AQI 事实核查：LLM 回答“오늘 강남 미세먼지 어때?”时引用实时站点数据，而非幻觉数值。
• 回填/研究面板：realtime --period 3MONTH 拉取单站 90 天数据，结合 kr-holiday-cli 分析假日交通效应。

不适用

• 亚小时或传感器级数据——AirKorea 仅小时级（延迟约 1h）；需分钟级请用 IoT 厂商（Awair、IQAir 合作）。
• 韩国以外 AQI——仅 한국환경공단 站点；其他国家请用 OpenAQ、AirNow、WAQI。
• 健康影响解释——API 仅返回浓度+等级，不含个性化健康建议；消费端请结合 WHO/CDC 文本。
• 高并发公网应用未用生产级 key——开发级上限每日每服务 1,000 次；请在 data.go.kr 申请生产级。

前置步骤

• 在 https://www.data.go.kr/ 注册（韩国开放数据门户，免费，无需企业身份）。
• 申请两项服务（开发级自动通过）：

- “한국환경공단_에어코리아_대기오염정보”（实时+预报） - “한국환경공단_에어코리아_측정소정보”（站点目录+TM 工具）

• 复制 Decoding key（原始形式，非 URL 编码）并导出：

export AIRKOREA_SERVICE_KEY='your_decoded_key_here' （可选）覆盖 endpoint： export ARPLTN_BASE='https://apis.data.go.kr/B552584/ArpltnInforInqireSvc' export MSRSTN_BASE='https://apis.data.go.kr/B552584/MsrstnInfoInqireSvc'

常用示例 A) 实时查看首尔所有站点 scripts/sido.sh --sido 서울 --num 60 | jq -c '{stationName, dataTime, pm10Value, pm25Value, pm10Grade, pm25Grade}'

B) 用 동 名找最近站点（完整链路） 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 scripts/realtime.sh --station 강남구 --period HOUR --num 1 | jq -c '{dataTime, pm25Value, pm25Grade, pm10Value, pm10Grade, o3Value, no2Value}'

C) 每日预报邮件标题 scripts/forecast.sh --date "$(date +%F)" --code PM25 | jq -r '"\(.informData) (\(.informCode)) — \(.informGrade // "-")"'

D) 90 天历史转 CSV scripts/realtime.sh --station 종로구 --period 3MONTH --num 1000 | jq -r '[.dataTime, .pm10Value, .pm25Value, .o3Value, .no2Value] | @csv' > jongno_90d.csv

E) 全国“非常差”警报 scripts/sido.sh --sido 전국 --num 1000 | jq -c 'select((.pm25Grade // "-") == "4")' # 每行输出 현재 매우나쁨 站点 → 接入告警系统

输出示例（realtime.sh） { "dataTime": "2026-04-29 09:00", "stationName": "강남구", … "pm25Grade": "2" }

等级对照（모든 *Grade 字段通用） 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+

错误码 AirKorea resultCode 含义 本 CLI 00 成功 返回 JSONL 99 / XML 体 未注册 key / 未用 Decoding key exit 22 01 应用错误 exit 22 04 HTTP 错误 exit 22 30 服务 key 权限不足 exit 22 12 已废弃 OpenAPI exit 22 33 日流量超限 exit 22

若 XML 返回 SERVICE_KEY_IS_NOT_REGISTERED_ERROR，说明用了 Encoded key；请在 data.go.kr 改用 Decoding key。