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 \x3Chttps://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:

   export KOSIS_API_KEY="N0NoeXVSRzlhUm5..."
   

3. 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

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: \x3Chttps://kosis.kr/openapi/devGuide/devGuide_0101.do>
• Error codes: \x3Chttps://kosis.kr/openapi/devGuide/devGuide_0103.do>
• Topic tree (browser): \x3Chttps://kosis.kr/statisticsList/statisticsListIndex.do>
• License: MIT (this CLI wrapper). The underlying data is public under 공공누리 제1유형.