# Korea Official Statistics (KOSIS) - English Time Series (`kdata-hub/kosis-korea-stats`) Actor

Fetch any KOSIS (Statistics Korea) table — no Korean account or API key needed — and get clean English-labelled, typed time series with per-row attribution.

- **URL**: https://apify.com/kdata-hub/kosis-korea-stats.md
- **Developed by:** [KData Hub](https://apify.com/kdata-hub) (community)
- **Categories:** Business, AI, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 result rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Korea Official Statistics (KOSIS) — English-normalized time series

Pull any table from **KOSIS** (Statistics Korea's official portal) — no Korean account needed — and get
analysis-ready rows: English labels, ISO periods (`2024-08`, `2024-Q3`, `2024-H2`), numeric values with
thousand separators removed, explicit `value_status` (`ok` / `missing` / `unparseable` — missing is never
turned into 0), and a per-row `attribution` block.

### Input

| field | example |
|---|---|
| `apiKey` | optional — leave empty to use built-in access, or use your own key from https://kosis.kr/openapi/ (secret, never logged) |
| `orgId` / `tblId` | `101` / table id from the kosis.kr table URL |
| `periodType` | `Y` `H` `Q` `M` `D` |
| `startPeriod` / `endPeriod` | `202001` / `202412` |
| `itemId`, `classL1` | default `ALL` |
| `maxRecords` | default 1000, max 50,000 (output says `truncated` when cut) |

### Output row

`table_id, table_name_ko, category_code, category_name_en/ko, item_id, item_name_en/ko, unit_en/ko,
frequency, period, period_status, period_raw, value, value_status, value_raw, english_complete, attribution{…}`

### Terms

KOSIS allows commercial use of its statistics **with attribution**, but forbids reselling them without
processing (https://kosis.kr/serviceInfo/useGuide.do). This actor transforms every row into a new schema and
attaches the source, organization, table, last-changed date, retrieval date and URL (KOSIS terms, Art. 7) — keep the
`attribution` field when you republish. International and North-Korea statistics are non-commercial only;
tables whose name marks them as such are refused (name-based check — verify your table if unsure).

### Your API key

KOSIS terms allow commercial use (Art. 8) and forbid transferring an API key (Art. 5). The actor's built-in key stays a secret environment variable and is never exposed to users; you may also supply your own key.

### Pricing

Pay per result (one dataset row = one `result` event).

### Example Output (Live 2026 Data)

Here are actual rows fetched by this actor. The actor automatically maps Korean labels to English, making the data instantly ready for Pandas or SQL.

**Economically Active Population (August 2026)**

```json
[
  {
    "category_name_en": "Total",
    "item_name_en": "Population 15 years old and over",
    "value": 46035.6,
    "unit_en": "Thousand Person"
  },
  {
    "category_name_en": "Total",
    "item_name_en": "Economically active population",
    "value": 29739.1,
    "unit_en": "Thousand Person"
  },
  {
    "category_name_en": "Total",
    "item_name_en": "Unemployment rate",
    "value": 2.0,
    "unit_en": "%"
  }
]
```

# Actor input Schema

## `apiKey` (type: `string`):

Optional. Leave empty to use the actor's built-in access. If you have your own free key from https://kosis.kr/openapi/ you can use it instead; it is used only for your run and never logged.

## `orgId` (type: `string`):

KOSIS organization id (101 = Statistics Korea).

## `tblId` (type: `string`):

KOSIS table id (tblId), shown in the table URL on kosis.kr, e.g. DT_1J22003 (Consumer Price Index).

## `periodType` (type: `string`):

Data frequency of the table. Y = yearly, H = half-yearly, Q = quarterly, M = monthly, D = daily.

## `startPeriod` (type: `string`):

First period to fetch: YYYY (yearly), YYYYMM (monthly), YYYY0Q (quarterly, e.g. 202403 = Q3), YYYYMMDD (daily).

## `endPeriod` (type: `string`):

Last period to fetch, same format as Start period.

## `itemId` (type: `string`):

KOSIS item id (ITM_ID). ALL = every item in the table.

## `classL1` (type: `string`):

KOSIS level-1 classification code (objL1). ALL = every category.

## `maxRecords` (type: `integer`):

Maximum number of rows to output. The run reports when the result was truncated.

## Actor input object example

```json
{
  "orgId": "101",
  "tblId": "DT_1J22003",
  "periodType": "M",
  "startPeriod": "202401",
  "endPeriod": "202406",
  "itemId": "T",
  "classL1": "T10",
  "maxRecords": 1000
}
```

# Actor output Schema

## `results` (type: `string`):

English-labelled, typed time-series rows with per-row attribution.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "orgId": "101",
    "tblId": "DT_1J22003",
    "startPeriod": "202401",
    "endPeriod": "202406",
    "itemId": "T",
    "classL1": "T10"
};

// Run the Actor and wait for it to finish
const run = await client.actor("kdata-hub/kosis-korea-stats").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "orgId": "101",
    "tblId": "DT_1J22003",
    "startPeriod": "202401",
    "endPeriod": "202406",
    "itemId": "T",
    "classL1": "T10",
}

# Run the Actor and wait for it to finish
run = client.actor("kdata-hub/kosis-korea-stats").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "orgId": "101",
  "tblId": "DT_1J22003",
  "startPeriod": "202401",
  "endPeriod": "202406",
  "itemId": "T",
  "classL1": "T10"
}' |
apify call kdata-hub/kosis-korea-stats --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kdata-hub/kosis-korea-stats"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/B2eNl2ynZS4MeVIxn/builds/fkLnyzmwdFWKS6K3B/openapi.json