Kosis Cli

Query Korea's national statistics portal (KOSIS, kosis.kr) via the official OpenAPI. Title search, category browsing, table metadata (items + dimensions + pe...

Security Scan

The skill is largely coherent with its stated purpose (wrapping the KOSIS OpenAPI), but the package metadata omits required environment variables and binaries and there are minor scope/configuration risks that the user should review before installing.

Purpose & Capability

The scripts and SKILL.md implement a KOSIS OpenAPI CLI (search, list, meta, data, bulk) which matches the name/description. However the registry metadata (provided earlier) says "Required env vars: none" and "Required binaries: none", while the scripts clearly require KOSIS_API_KEY and the binaries curl and jq. That mismatch is an omission in the metadata (incoherent) but the actual requirements are appropriate for the declared purpose.

Instruction Scope

The runtime instructions and scripts only call KOSIS endpoints (statisticsList.do, statisticsData.do, statisticsSearch.do, statisticsBigData.do) and emit JSONL. They read a single API key from the KOSIS_API_KEY environment variable and do not write persistent files. One scope risk: the base URL is configurable via KOSIS_BASE (environment override), so if an operator or environment sets KOSIS_BASE to a malicious endpoint, the scripts would send the KOSIS_API_KEY and queries to that endpoint. Also the SKILL.md instructs the user to export KOSIS_API_KEY, but the skill registry failed to declare it.

Install Mechanism

No install spec or third-party downloads; this is an instruction-and-scripts bundle (shell scripts). That is low-install risk because nothing is downloaded or auto-executed during install. The included scripts will run when invoked.

Credentials

The scripts legitimately require a KOSIS_API_KEY and standard CLI tools (curl, jq). Those credentials/binaries are proportionate to the skill's purpose. The concern is that the skill registry metadata omitted these requirements, which may lead users/automated installers to run it without providing the key or without realizing the scripts will read KOSIS_API_KEY from the environment. The presence of the sensitive KOSIS_API_KEY is justified, but must be declared. Also note that KOSIS_BASE can be overridden, which combined with an API key could cause unintended disclosure if misconfigured.

Persistence & Privilege

The skill does not request persistent presence (always:false), does not modify other skills or system settings, and does not store tokens. It only reads environment variables at runtime. No elevated privileges or forced inclusion detected.

What to consider before installing

This skill is a straightforward CLI wrapper around the KOSIS OpenAPI and generally does what it claims. Before installing or running it: 1) Be aware you must export a KOSIS_API_KEY (the scripts call require_key) — the registry metadata omitted this, so set KOSIS_API_KEY yourself. 2) Ensure curl and jq are available on the host (the scripts call require_bin). 3) Do not set KOSIS_BASE to an untrusted URL; if an environment overrides KOSIS_BASE the scripts will send your API key and queries to that endpoint. 4) Review the scripts locally (they are small shell scripts) and run them in a sandbox or with a limited API key if possible. 5) If you expect registry metadata to be authoritative (for automated installs), ask the publisher to correct the metadata to declare KOSIS_API_KEY and required binaries. These discrepancies look like sloppy metadata rather than malicious intent, but confirm the origin of the package before trusting credentials.

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

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