🏦 Korea BoK Monetary Policy + ECOS Macro Data

Live Bank of Korea base rate (기준금리), monetary aggregates (M1/M2), GDP, CPI, FX reserves, and trade balance — KRW-denominated source-of-truth feed from the official BoK ECOS Open API.

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.

---

⚡ 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

1. KRW/USD FX desks — daily BoK base rate + monthly FX reserves + trade balance in one async pull instead of three terminal screens.
2. EM-rates PMs — quarterly real/nominal GDP + monthly CPI feed for Korea sleeve of EM-local rates portfolio.
3. Korean equity strategists — pair with kospi-stock-screener and tse-japan-stock-screener for the full Korea-Japan equity-vs-macro overlay.
4. AI macro agents — clean structured rows to answer "what's the current BoK base rate" or "what was Korean CPI YoY in March".
5. Research / academia — long-window stable BoK time series (base rate back to 1999, CPI back to 1965 monthly) for monetary-economics papers.
6. Bond-duration management — Korea sovereign rate path for KTB curve positioning + KRW reserve-recycling flow into US Treasuries.

---

📊 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.

---

📥 Sample input

{
  "bok_ecos_api_key": "YOUR_ECOS_KEY_HERE",
  "data_type": "all",
  "cycle": "M",
  "date_from": "2025-01-01",
  "date_to": "2026-05-31",
  "max_records": 100
}

Variants:

• Just the base rate (daily, last 30 days): {"bok_ecos_api_key": "...", "data_type": "base_rate", "cycle": "D", "date_from": "2026-05-01", "date_to": "2026-05-31"}
• 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/.../json/kr/1/100/722Y001/D/20260501/20260531",
    "fetched_at": "2026-05-31T12:00:00+00:00"
  },
  {
    "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/.../json/kr/1/100/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 (no crash).

---

🔗 Related Actors

Pair with these production-grade NexGenData siblings for full APAC-macro / equity coverage:

• 🇰🇷 KOSPI Stock Screener — Korean equity universe (KOSPI / KOSDAQ tickers, GICS sectors, fundamentals) — natural pair for KOSPI-vs-base-rate analysis.
• 🇯🇵 TSE Japan Stock Screener — Japanese equity universe — pair for the Korea-Japan equity-vs-macro overlay desks run.
• 🇯🇵 Japan EDINET Insider Filings — Japanese FSA EDINET corporate filings — adjacent regulatory feed for Japan-Korea cross-market desks.
• 📅 APAC IPO Calendar Sweep — Asia-Pacific IPO calendar (TSE / KOSPI / HKEX / SGX) — primary-market companion to this secondary-market macro feed.
• 📢 SGX Company Announcements — Singapore Exchange disclosures — second key APAC-financial-hub feed.
• 💱 Currency Exchange Rates — Live FX rates — pair with BoK base rate + KRW reserves for the full KRW-flow picture.
• 📈 Stock Exchange Meta Scraper — Global exchange registry — useful for cross-listing checks against Korean ADRs.

---

📜 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)).