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:

search — keyword search across statistic titles (e.g. "소비자물가", "출생").
list — browse the statistics tree by topic/agency (참조 ID listing).
meta — fetch metadata for a specific table: classification items, period type, last updated.
data — pull actual numeric data for a (orgId, tblId) with item/dimension/period filters.
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

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.

Export it:

export KOSIS_API_KEY="N0NoeXVSRzlhUm5..."

Dependencies: bash, curl, jq (default on macOS/Linux).

Commands

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

{"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유형.