Skill: chloepark85/kosis-cli (version 0.1.0)

--- name: kosis-cli description: Query Korea's national statistics portal (KOSIS, kosis.kr) via the official OpenAPI. Title search, category browsing, table metadata (items + dimensions + periods), and actual statistics data — population, employment, prices, business demographics, household income, regional indicators, etc. Use when a task needs Korean national statistics by organization/topic — e.g. "monthly CPI 2020-2025", "population by 시군구", "employment rate by age band", "household income decile". Pairs with bank-of-korea-ecos-cli (macro) and opendart-cli (corporate filings) to complete the Korean public-data toolchain. version: 0.1.0 license: MIT --- # kosis-cli Minimal command-line wrapper for **KOSIS — 국가통계포털 (Korean Statistical Information Service)** OpenAPI. KOSIS is the central registry for Korean national statistics maintained by Statistics Korea (통계청), aggregating ~1,000 datasets from 100+ government agencies. This wrapper exposes five operations: 1. `search` — keyword search across statistic titles (e.g. "소비자물가", "출생"). 2. `list` — browse the statistics tree by topic/agency (참조 ID listing). 3. `meta` — fetch metadata for a specific table: classification items, period type, last updated. 4. `data` — pull actual numeric data for a `(orgId, tblId)` with item/dimension/period filters. 5. `bulk` — pull a large pre-saved `userStatsId` slice (saved on kosis.kr OpenAPI 활용신청). All output is compact JSON (`format=json&jsonVD=Y`), one row per line (JSONL) so it pipes directly into `jq`. ## When to use this skill Use when the task is **Korean national statistics shaped**: - "Monthly CPI from 2020 to last month" - "Population of every 시군구 in the latest census year" - "Employment rate by gender × age band, 2024" - "Number of newly registered businesses by industry, 통계청 기준" - "Household income, 5분위, by year" Do **not** use this skill for: - **Macro-economic time series** (rates, FX, money supply, GDP components) → use `bank-of-korea-ecos-cli` (ECOS is more granular and timely for those). - **Listed-company financial statements** → use `opendart-cli`. - **Stock prices** → use `krx-stock-cli`. - **Real-estate transaction data** → use the Ministry of Land's RTMS API (not yet wrapped). ## Prerequisites 1. Get an API key (인증키) at <https://kosis.kr/openapi/devGuide/devGuide_0102.do>. Sign up with a 통합인증 (KOSIS) account, click 활용 신청, fill out the application — keys are auto-issued instantly for the public catalog. 2. Export it: ```bash export KOSIS_API_KEY="N0NoeXVSRzlhUm5..." ``` 3. Dependencies: `bash`, `curl`, `jq` (default on macOS/Linux). ## Commands ```bash # 1) Title search scripts/search.sh "소비자물가" scripts/search.sh "출생률" --page 1 --per-page 20 # 2) Browse the catalog tree scripts/list.sh # top-level topic categories scripts/list.sh --vw-cd MT_OTITLE # browse by agency instead of topic scripts/list.sh --parent A # children of category A (인구·가구) # 3) Metadata for a specific table # orgId=101 (통계청), tblId=DT_1B040A3 (주민등록인구현황) scripts/meta.sh 101 DT_1B040A3 scripts/meta.sh 101 DT_1B040A3 --type ITM # only classification items scripts/meta.sh 101 DT_1B040A3 --type OBJ # only object dimensions # 4) Actual data # Most-recent 3 monthly periods, all items, all L1 objects scripts/data.sh 101 DT_1B040A3 --prd-se M --recent 3 # Specific period range with explicit item & objects scripts/data.sh 101 DT_1B040A3 \ --prd-se M \ --from 202401 --to 202412 \ --itm "T20 T21" \ --obj-l1 "11 21 22" \ --obj-l2 ALL # 5) Bulk fetch by user-saved slice # (after 활용신청 on kosis.kr, you receive userStatsId values) scripts/bulk.sh 134567 --recent 12 ``` Every script prints one JSON object per line on stdout; errors go to stderr with a non-zero exit code. ## Example JSONL output (`data.sh`) ```jsonl {"PRD_DE":"202412","PRD_SE":"M","TBL_NM":"행정구역(시군구)별 주민등록인구","ITM_NM":"총인구수","C1_NM":"전국","DT":"51234567","UNIT_NM":"명","ORG_ID":"101","TBL_ID":"DT_1B040A3"} ``` Field cheatsheet: - `PRD_DE` — period (YYYYMM for M, YYYY for Y, YYYYQ for Q) - `PRD_SE` — period type (M/Q/Y/H/IR) - `ITM_NM` / `ITM_ID` — measure (e.g. "총인구수", "남자") - `C1_NM` … `C8_NM` — dimension labels (region, age, etc.) — number depends on table - `DT` — value (string; cast to number caller-side) - `UNIT_NM` — unit ("명", "원", "%", …) ## Rate limits & quotas - Default key: **10,000 requests/day**, soft cap. - Per-call response cap: **10,000 rows**. Use `--page` / `--per-page` (max 100,000 for `bulk`) and tighten with `--recent N` or explicit `--from/--to` when the slice is wide. - The scripts **do not** retry on 429 / quota-exceeded — back off in the caller. ## Common `vwCd` (view code) values for `list` | vwCd | Tree | |---|---| | `MT_ZTITLE` (default) | 국내통계 주제별 (population, prices, labor, …) | | `MT_OTITLE` | 국내통계 기관별 (Statistics Korea, KEPCO, MOLIT, …) | | `MT_CHITLE` | 대상별 통계 (women, youth, seniors, …) | | `MT_GTITLE01` | e-지방지표 주제별 | | `MT_GTITLE02` | e-지방지표 지역별 | ## Notes for agents - **`orgId` + `tblId` is the primary key** of any table. Always start from `search` or `list` to discover it; do not guess. - KOSIS items (`itmId`) and objects (`objL1` … `objL8`) are **table-specific** — always run `meta.sh` first to learn the codes for a table you haven't touched before. - For period-aware tables, `prdSe` is required: `M` (월), `Q` (분기), `Y` (연), `H` (반기), `IR` (부정기). - `--recent N` is shorthand for `newEstPrdCnt=N` and is the simplest way to get "the latest N periods" without computing dates. - A 0-row response is a valid result (filter matched nothing); a row with `err` indicates a parameter mismatch. - Korean column names (`*_NM`) are present alongside codes (`*_ID`) — prefer codes for joins/filters, names for display. ## Reference - KOSIS OpenAPI dev guide: <https://kosis.kr/openapi/devGuide/devGuide_0101.do> - Error codes: <https://kosis.kr/openapi/devGuide/devGuide_0103.do> - Topic tree (browser): <https://kosis.kr/statisticsList/statisticsListIndex.do> - License: MIT (this CLI wrapper). The underlying data is public under 공공누리 제1유형.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)