🇰🇷 Korea BoK Monetary Policy — Base Rate, CPI & ECOS Macro

Korea's macro data lives inside the Bank of Korea ECOS Open API, a powerful but key-gated system that rate-limits each user to roughly 1,000 calls a day. This actor wraps ECOS behind a clean schema: supply your own free ECOS key and it returns the base rate, M1/M2 aggregates, real and nominal GDP, CPI, FX reserves and the BoP trade balance as normalized bilingual rows. No shared key means no neighbour can exhaust your quota, and a missing key returns one graceful error row instead of a crash.

Built for KRW/USD FX traders, EM-rates PMs, Korean equity strategists, macro hedge-fund analysts, and AI-agent integrations that need clean, structured Korea monetary data without paying $24K/yr for a Bloomberg terminal.

Billing note: because every pushed row (including a graceful error row) charges the macro-record event, a keyless run, an invalid-key run, or a rate-limited (ERROR-602) run returns one billable error row ($0.05). Supply a valid ECOS key to get real data rows.

---

⚡ What you get

Per record (stable 9-field schema):

Field	Description
data_type	One of base_rate, krw_reserves, monetary_aggregates, gdp, cpi, trade_balance
stat_code	ECOS statistic code (e.g. 722Y001 for base rate, 901Y009 for CPI)
stat_name_kr	Series name in Korean (e.g. "한국은행 기준금리"), with sub-item label appended
stat_name_en	Series name in English (e.g. "BoK base rate")
period	ECOS period string — YYYYMMDD (daily) / YYYYMM (monthly) / YYYYQn (quarterly) / YYYY (annual)
value	Numeric value (rate %, KRW billion, USD million, index level)
unit	Unit string (e.g. % per annum, KRW billion, USD million, index)
source_url	The exact ecos.bok.or.kr/api/StatisticSearch/... URL the row came from
fetched_at	UTC timestamp of the actor fetch

---

🎯 Use cases

• KRW/USD desk — daily base rate + monthly FX reserves + trade balance in one pull instead of three terminal screens.
• EM-rates PM — quarterly real/nominal GDP + monthly CPI for the Korea sleeve of an EM-local book.
• Bond-duration management — BoK rate path for KTB curve positioning + KRW reserve-recycling flow into US Treasuries.
• AI macro agent — clean structured rows to answer "current BoK base rate?" or "Korean CPI YoY in March?"
• Long-window academic panels — stable BoK series (base rate back to 1999, CPI back to 1965 monthly) for monetary-economics papers.

---

📊 Sample Output

The dashboard renders the current BoK base rate (기준금리), the latest M1/M2 monetary aggregates, KRW FX reserves, CPI level + YoY trend, and the latest trade balance print — all in one image with full Korean terminology rendered in Noto Sans CJK KR.

---

🇰🇷 한국어 설명

한국은행 경제통계시스템(ECOS) Open API를 통해 한국 기준금리, 통화량(M1/M2), GDP, CPI, 외환보유고 등 주요 거시 경제 지표를 구조화된 데이터로 제공합니다.

주요 용도:

• 한국 매크로 분석
• KRW/USD 환율 트레이딩
• 채권 듀레이션 관리
• 한국 통화정책 모니터링

본 액터는 한국은행 ECOS Open API 이용약관에 따라 사용자별 개인 인증키(약 1,000 calls/day 제한)를 요구합니다. 공유 키는 제공하지 않습니다. 무료 키 발급: https://ecos.bok.or.kr/api/

---

🔑 API key (required)

You must supply your own free BoK ECOS Open API key. Register at https://ecos.bok.or.kr/api/ — registration is free, takes about 2 minutes, and asks for an email + intended use. Once registered, BoK emails you a raw alphanumeric key.

Why a personal key? ECOS terms-of-service rate-limit each key to roughly 1,000 calls per day. We could ship a shared key, but if a single high-volume buyer ran a backfill it would block every other buyer for the rest of the day. Personal keys give you a clean 1,000-call/day quota that nobody else can exhaust.

If you forget to set the key (or paste a placeholder like "TEST"), the actor exits cleanly with a single error record explaining the issue — it will not crash or fail Apify QA. Note: that single error row is still a billable macro-record.

---

📥 Sample input

{
  "bok_ecos_api_key": "YOUR_ECOS_KEY",
  "data_type": "base_rate",
  "cycle": "D",
  "date_from": "2026-05-01",
  "date_to": "2026-05-31"
}

Variants:

• Full snapshot (all series, monthly): {"bok_ecos_api_key": "...", "data_type": "all", "cycle": "M", "date_from": "2025-01-01", "date_to": "2026-05-31", "max_records": 100}
• Just CPI (monthly, last 5 years): {"bok_ecos_api_key": "...", "data_type": "cpi", "cycle": "M", "date_from": "2021-01-01", "date_to": "2026-05-31"}
• Specific ECOS stat code (advanced): {"bok_ecos_api_key": "...", "stat_code_filter": "731Y004", "cycle": "M"}

---

📤 Sample output

{
  "data_type": "base_rate",
  "stat_code": "722Y001",
  "stat_name_kr": "한국은행 기준금리 — 한국은행 기준금리",
  "stat_name_en": "BoK base rate — 한국은행 기준금리",
  "period": "20260514",
  "value": 2.75,
  "unit": "% per annum",
  "source_url": "https://ecos.bok.or.kr/api/StatisticSearch/.../722Y001/D/20260501/20260531",
  "fetched_at": "2026-05-31T12:00:00+00:00"
}

A CPI row (data_type=cpi):

{
  "data_type": "cpi",
  "stat_code": "901Y009",
  "stat_name_kr": "소비자물가지수 (2020=100) — 총지수",
  "stat_name_en": "Consumer price index (2020=100) — 총지수",
  "period": "202604",
  "value": 116.05,
  "unit": "index",
  "source_url": "https://ecos.bok.or.kr/api/StatisticSearch/.../901Y009/M/202401/202605",
  "fetched_at": "2026-05-31T12:00:00+00:00"
}

---

🔄 How the data flows

Stage	What happens
1. Plan	Expand data_type (or stat_code_filter) into a list of (stat_code, cycle) pairs from the built-in registry — base rate 722Y001/D, KRW reserves 731Y001/M, M1/M2 101Y002/101Y003/M, GDP 200Y102/111Y018/Q, CPI 901Y009/M, trade balance 301Y013/M.
2. Encode period	Convert ISO date_from/date_to into ECOS period strings — YYYYMMDD, YYYYMM, YYYYQn, or YYYY based on the cycle.
3. Fetch	Per stat code: GET /api/StatisticSearch/{key}/json/kr/1/{endIdx}/{statCode}/{cycle}/{start}/{end} with a polite identified User-Agent.
4. Detect errors	If ECOS returns {"RESULT": {"CODE": "ERROR-...", "MESSAGE": "..."}} (invalid key, rate-limited, no data), emit a single error record with the ECOS code instead of crashing.
5. Normalize	For each ECOS row, extract STAT_CODE, STAT_NAME, ITEM_NAME1..4 (sub-item labels like M1 vs M2 or exports vs imports), TIME, DATA_VALUE, UNIT_NAME. Cast value to float.
6. Emit	Actor.push_data(record) + Actor.charge("macro-record") per row, up to max_records.

---

⏱️ Rate limit reality

BoK ECOS terms-of-service cap each key at ~1,000 calls/day. This actor makes one HTTP call per stat code per run, so a data_type="all" run uses 8 calls (one for each of the 8 codes in the registry). At default max_records=100, you can run this actor 100+ times/day without coming close to the cap. If you do hit it, ECOS returns {"RESULT": {"CODE": "ERROR-602", "MESSAGE": "과도한 OpenAPI호출..."}} and this actor emits a clean error record (still one billable row).

---

❓ FAQ

Q: Why do I need my own key? A: ECOS rate-limits each key to ~1,000 calls/day. A shared key would let one heavy user block everyone, so personal keys give you a clean quota that nobody else can exhaust.

Q: What if I forget the key? A: The actor exits cleanly with one error record (no crash). Note that single row is still a billable macro-record.

Q: How many ECOS calls per run? A: One per stat code; a data_type=all run uses 8.

Q: How current is each series? A: Base rate daily; CPI / M1 / M2 / reserves / trade balance monthly; GDP quarterly.

---

🔗 Related Actors

Part of the NexGenData APAC macro / central-bank cluster — composable into any cross-border macro, FX or rates workflow:

• 🇯🇵 Japan BoJ Macro Rates + JGB Auctions — BoJ call/policy rates, JGB yield curve (1974→) + auction calendar, money stock, FX reserves, MPM statements.
• 💴 Japan MoF FX Intervention Tracker — MoF yen-intervention record back to 1991, parsed from the FEIO CSV.
• 🇹🇼 Taiwan CBC Macro + FX Rates — Bank of Taiwan daily TWD FX matrix + CBC policy rate, money supply and reserves.
• 🇮🇳 India RBI Monetary Policy Statements — RBI MPC repo-rate decisions, stance, CRR/SLR and forecasts as structured rows.
• 🇹🇼 Taiwan Customs Export Trade Data — Taiwan export / import / trade-balance data by partner country and HS code.

---

📜 Legal posture

• Source: BoK ECOS Open API at ecos.bok.or.kr/api/StatisticSearch/.... Statistical publication mandated by Bank of Korea Act §86 and the Korean Public Data Act §17 (open commercial reuse).
• License: ECOS terms of service §3 permit research, commercial use, and redistribution with attribution. No PII.
• Rate limit: ~1,000 calls/day per registered key (ECOS ToS). This actor surfaces ECOS rate-limit envelopes (ERROR-602) as graceful error rows.
• Polite identified User-Agent declared on every request (NexGenData BoK ECOS Macro Actor (hello@thenextgennexus.com)).