ClawHub

Kosis Cli

Productivity

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.

Install

openclaw skills install @chloepark85/kosis-cli

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: 
    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

vwCdTree
MT_ZTITLE (default)국내통계 주제별 (population, prices, labor, …)
MT_OTITLE국내통계 기관별 (Statistics Korea, KEPCO, MOLIT, …)
MT_CHITLE대상별 통계 (women, youth, seniors, …)
MT_GTITLE01e-지방지표 주제별
MT_GTITLE02e-지방지표 지역별

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

More in Productivity