# KOSIS Korea Macro Indicators - 통계청 거시경제 지표 (`gochujang/kosis-macro-indicators`) Actor

Fetches Korea macro-economic indicators from Statistics Korea (KOSIS) API. Covers GDP, CPI, retail sales, unemployment, service production and 200+ economic indicators.

- **URL**: https://apify.com/gochujang/kosis-macro-indicators.md
- **Developed by:** [Hojun Lee](https://apify.com/gochujang) (community)
- **Categories:** Business
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## KOSIS Korea Macro Indicators

Fetch South Korea macro-economic indicators from **Statistics Korea (KOSIS) OpenAPI**. Collect GDP growth, CPI, unemployment, industrial production, retail sales, housing prices and more — all from the official government data source.

### Features

- 7 preset indicators with correct KOSIS table codes
- Custom indicator support via `orgId:tblId` format (access 200+ KOSIS tables)
- Monthly or annual data
- Configurable date range
- Pay-per-event pricing — only pay for data you receive

### Prerequisites

1. Register at [KOSIS OpenAPI](https://kosis.kr/openapi/) (free)
2. Apply for an API key (approved within 1–2 business days)
3. Pass your key in the `api_key` input field

### Input

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `api_key` | string | ✅ | — | KOSIS OpenAPI authentication key |
| `indicators` | array | ✅ | `["cpi","unemployment"]` | Preset keywords or `orgId:tblId` codes |
| `start_period` | string | | 12 months ago | Start period `YYYYMM` (monthly) or `YYYY` (annual) |
| `end_period` | string | | Current month | End period `YYYYMM` or `YYYY` |
| `period_type` | string | | `monthly` | `monthly` or `annual` |
| `language` | string | | `en` | Output language for indicator names: `en` or `kr` |

### Preset Indicators

| Keyword | Indicator | Source Table |
|---------|-----------|-------------|
| `gdp` | GDP Growth Rate | 301 / DT\_200Y003 |
| `cpi` | Consumer Price Index | 101 / DT\_1J20006 |
| `retail_sales` | Retail Sales Index | 101 / DT\_1L9H001 |
| `unemployment` | Unemployment Rate | 101 / DT\_1DA7002S |
| `service_production` | Service Production Index | 101 / DT\_1L9H002 |
| `industrial_production` | Industrial Production Index | 101 / DT\_1L9B001 |
| `housing_price` | Housing Price Index | 408 / DT\_KAB\_12001\_S1 |

### Custom Indicators

Pass any KOSIS table using the `orgId:tblId` format:

```json
{
  "indicators": ["101:DT_1DA7002S", "301:DT_200Y003"]
}
```

Browse available tables at [KOSIS Statistical DB](https://kosis.kr/statHtml/statHtml.do).

### Output Fields

Each dataset item contains:

| Field | Description |
|-------|-------------|
| `indicator_key` | Preset keyword or raw code |
| `indicator_name` | Human-readable indicator name |
| `item_name` | KOSIS item sub-classification name |
| `classification` | KOSIS classification code (C1) |
| `period` | Period string (`YYYYMM` or `YYYY`) |
| `value` | Numeric value (null if not available) |
| `unit` | Unit (%, index, etc.) |
| `org_id` | KOSIS organization ID |
| `tbl_id` | KOSIS table ID |
| `source` | Always `"KOSIS - Statistics Korea"` |

### Example Output

```json
{
  "indicator_key": "cpi",
  "indicator_name": "Consumer Price Index",
  "item_name": "총지수",
  "classification": "",
  "period": "202412",
  "value": 115.7,
  "unit": "index",
  "org_id": "101",
  "tbl_id": "DT_1J20006",
  "source": "KOSIS - Statistics Korea"
}
```

### Pricing

| Event | Price |
|-------|-------|
| Actor start | $0.001 |
| Per data point returned | $0.001 |

Fetching 7 indicators over 12 months typically returns 80–100 data points (~$0.10).

### Data Source

All data is sourced from [Statistics Korea (KOSIS)](https://kosis.kr/), the official statistical portal of the Korean government.

### Legal

This Actor retrieves publicly available data via the official KOSIS OpenAPI under the [공공데이터 이용허락](https://kosis.kr/serviceInfo/openApiGuide.do) terms. Use of this Actor is subject to the KOSIS API terms of service.

**Keywords:** KOSIS, South Korea macroeconomics, GDP, CPI, unemployment, Statistics Korea, Korean economy, economic indicators, macro data

# Actor input Schema

## `mode` (type: `string`):

key\_statistics: latest values for ~101 indicators (CPI, GDP, unemployment, rates, etc). timeseries: historical data for selected indicators. both: all of the above.

## `categories` (type: `array`):

Filter key\_statistics by category. Leave empty for all. Examples: CPI, Employment, Exchange Rates, Money Supply, Growth Rates, Stock Market, Real Estate Prices, Trade.

## `ts_indicators` (type: `array`):

Which time-series indicators to fetch (used when mode=timeseries or both). Available: bok\_base\_rate, deposit\_rate, usd\_krw, jpy\_krw, eur\_krw, kospi, kosdaq.

## `start_date` (type: `string`):

Start date for time-series. Format depends on indicator: Daily=YYYYMMDD, Monthly=YYYYMM. Defaults to 90 days ago (daily) or 12 months ago (monthly).

## `end_date` (type: `string`):

End date for time-series. Same format as start\_date. Defaults to today.

## `language` (type: `string`):

Output language for indicator category names.

## `api_key` (type: `string`):

Deprecated — no longer needed. This actor now uses BOK ECOS public data without any API key.

## Actor input object example

```json
{
  "mode": "key_statistics",
  "categories": [],
  "ts_indicators": [
    "bok_base_rate",
    "usd_krw",
    "kospi"
  ],
  "language": "en"
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("gochujang/kosis-macro-indicators").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("gochujang/kosis-macro-indicators").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 '{}' |
apify call gochujang/kosis-macro-indicators --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gochujang/kosis-macro-indicators"
        }
    }
}

```

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/2iDL9ST8ce7IsVeiM/builds/jZekJVMQGzvgLGRQY/openapi.json