# Bank of Korea ECOS - English Economic Time Series (`kdata-hub/ecos-korea-stats`) Actor

Fetch Bank of Korea (ECOS) statistics — rates, FX, CPI, GDP, money supply — as clean English-labelled time series (ISO periods, numeric values, missing flags, per-row attribution). No Korean account or API key needed.

- **URL**: https://apify.com/kdata-hub/ecos-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

## Bank of Korea ECOS — English Economic Time Series

Fetch official **Bank of Korea** statistics from ECOS (Economic Statistics System) as clean, English-labelled, typed rows — **no Korean account or API key needed**.

- Interest rates (BOK base rate, call rate, KORIBOR, bond yields), KRW exchange rates, CPI / PPI, GDP, money supply, deposits & loans, balance of payments, business surveys and ~600 more tables
- ISO periods (`2024`, `2024-H1`, `2024-Q3`, `2024-01`, `2024-01-S1`, `2024-01-02`), numeric values, explicit `missing` / `unparseable` flags — nothing silently dropped
- Every row carries a stable `series_id` and attribution to the Bank of Korea
- Automatic paging (up to 100,000 rows per run)

**Typical searches this actor answers:** Bank of Korea base rate history · KRW/USD exchange rate history · Korea GDP data · Korea money supply (M2) · Korean government bond yields · ECOS API in English.

### Use cases

- **Rates** — BOK base rate, call rate, KORIBOR and Korean government bond yields (daily or monthly).
- **FX** — KRW exchange rates (e.g. KRW/USD) as clean daily or monthly series.
- **Macro** — GDP, CPI / PPI, money supply, deposits & loans, balance of payments.
- **Dashboards** — `keyStatistics` mode returns ~100 headline indicators in one run.
- **AI agents & research assistants** — English rows with Bank of Korea attribution, ready to cite.

### Modes

| mode | what you get | input |
|---|---|---|
| `series` (default) | observations of one table | `statCode`, `frequency`, `startPeriod`, `endPeriod`, optional `itemCode1..4` |
| `keyStatistics` | ~100 headline indicators, latest values | nothing else |
| `items` | item codes, frequencies and date ranges of a table | `statCode` |

Leave `itemCode1` empty to get every item of a table. Not sure about codes? Run `items` first.

### Quick start

CPI, monthly, 2024:

```json
{"statCode": "901Y009", "frequency": "M", "startPeriod": "202401", "endPeriod": "202412", "itemCode1": "0"}
```

BOK base rate, daily:

```json
{"statCode": "722Y001", "frequency": "D", "startPeriod": "20260901", "endPeriod": "20261010", "itemCode1": "0101000"}
```

Headline dashboard: `{"mode": "keyStatistics"}`

### Use it from an AI agent (MCP)

Apify's MCP server (`https://mcp.apify.com`) lets MCP clients such as Claude Desktop, Claude Code, Cursor or VS Code call public Store actors. Add the server to your client, then ask, for example:

> Use the Apify actor `kdata-hub/ecos-korea-stats` to get the Bank of Korea base rate (statCode `722Y001`, itemCode1 `0101000`, frequency `D`) from 2026-01-01 to today and list each change.

Not sure about codes? Ask the agent to run the actor in `items` mode for a table first.

### Output (series)

```json
{
  "series_id": "901Y009.M.0",
  "stat_code": "901Y009",
  "stat_name_en": "Consumer Price indices",
  "items": [{"level": 1, "code": "0", "name_en": "Total item"}],
  "item_path_en": "Total item",
  "unit_en": "2020=100",
  "frequency": "M",
  "period": "2024-01",
  "value": 113.17,
  "value_status": "ok",
  "attribution": {"source": "Bank of Korea, Economic Statistics System (ECOS)", "stat_code": "901Y009", "retrieved_at": "2026-10-13", "url": "https://ecos.bok.or.kr/"}
}
```

Period formats for input: A = `YYYY`, S = `YYYYS1`, Q = `YYYYQ1`, M = `YYYYMM`, SM = `YYYYMMS1`, D = `YYYYMMDD`.

### Pricing

Pay per result: **$0.002 per row ($2 per 1,000 rows)**. `keyStatistics` is ~100 rows (about $0.20). A run that returns no rows produces no result charges.

### FAQ

**Do I need a Korean account or an ECOS API key?** No. The actor uses built-in access by default; you can supply your own free ECOS key in `apiKey`.

**Is the data official?** Yes — values come from the Bank of Korea's Economic Statistics System (ECOS) and every row carries attribution. This actor is not affiliated with the Bank of Korea.

**How do I find a table code?** Run `items` mode with a `statCode`, or start from `keyStatistics` and the codes shown there.

### Notes

- Source: Bank of Korea, Economic Statistics System (ECOS). This actor is not affiliated with the Bank of Korea.
- Optional: bring your own free ECOS key (`apiKey`). It is used only for your run and never logged.
- An empty result means ECOS has no data for that table / period / item combination.

# Actor input Schema

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

series = fetch observations for statCode. keyStatistics = Bank of Korea's ~100 headline indicators, latest values (no other input needed). items = list the item codes, frequencies and date ranges available in statCode.

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

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

## `statCode` (type: `string`):

ECOS table code (STAT_CODE), e.g. 901Y009 = Consumer Price Index, 722Y001 = Bank of Korea base rate, 731Y001 = KRW exchange rates. Not needed for keyStatistics.

## `frequency` (type: `string`):

Frequency of the series. Use mode 'items' to see which frequencies a table offers.

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

Format depends on frequency: A = YYYY, S = YYYYS1, Q = YYYYQ1, M = YYYYMM, SM = YYYYMMS1, D = YYYYMMDD.

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

Last period to fetch, same format as Start period.

## `itemCode1` (type: `string`):

ECOS item code (ITEM_CODE1). Leave empty to fetch every item of the table. Use mode 'items' to list codes.

## `itemCode2` (type: `string`):

Second-level item code, only for tables with more than one item dimension. itemCode3 / itemCode4 can be passed in JSON input.

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

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

## Actor input object example

```json
{
  "mode": "series",
  "statCode": "901Y009",
  "frequency": "M",
  "startPeriod": "202401",
  "endPeriod": "202412",
  "itemCode1": "0",
  "maxRecords": 1000
}
```

# Actor output Schema

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

English-labelled, typed rows with per-row Bank of Korea 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 = {
    "statCode": "901Y009",
    "startPeriod": "202401",
    "endPeriod": "202412",
    "itemCode1": "0"
};

// Run the Actor and wait for it to finish
const run = await client.actor("kdata-hub/ecos-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 = {
    "statCode": "901Y009",
    "startPeriod": "202401",
    "endPeriod": "202412",
    "itemCode1": "0",
}

# Run the Actor and wait for it to finish
run = client.actor("kdata-hub/ecos-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 '{
  "statCode": "901Y009",
  "startPeriod": "202401",
  "endPeriod": "202412",
  "itemCode1": "0"
}' |
apify call kdata-hub/ecos-korea-stats --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kdata-hub/ecos-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/N44e3Nt2pfH7sJVI9/builds/WdSs1VtbfEbr8gtPG/openapi.json