kosis-stats

KOSIS Stats automates read-only retrieval of official Korean government statistics through the KOSIS (Korean Statistical Information Service, kosis.kr) Open API operated by Statistics Korea. It lets users search official statistical tables and fetch metadata, data cells, and large datasets for topics like population, households, prices, and employment. The skill is explicitly query-only: it does not create, modify, register, or publish statistics, and it is meant for pulling raw numbers rather than analysis or visualization.

A Python helper (stdlib-only, Python 3.9+) exposes subcommands for search, metadata, data, bigdata, list, explain, and indicator, covering endpoints such as statistics search, table metadata, parameterized data-cell queries, large-volume datasets requiring a pre-registered userStatsId, the category tree, statistical explanations, and key-indicator concepts. Common options include human-readable or JSON output, a dry-run mode that prints the request URL and parameters without a key, timeout control, and a direct mode. By default general queries route through a hosted or self-hosted k-skill proxy that injects the KOSIS key server-side, so most usage needs no local credentials; only bigdata or direct calls read a KOSIS API key. Credential resolution is handled safely, preferring existing environment variables, then an agent's own secret vault (1Password, Bitwarden, macOS Keychain), then a fallback dotenv file at 0600 permissions, and its guidance stresses never committing keys, masking keys in dry-run output, and respecting the API rate limit. A reference guide documents key issuance, limits, endpoints, response quirks, and error codes, backed by tests and fixtures.

The target users are analysts, researchers, and developers who need programmatic access to authoritative Korean statistics and want a safe, well-documented CLI wrapper. It is not for real-time market data, visualization, or statistics authoring.