k-ecos
Queries the Bank of Korea Economic Statistics System (`한국은행 경제통계시스템 ECOS`) Open API for Korean macro-financial statistics — base rate, exchange rates, money supply, interest rates, GDP, and the `100대 통계지표` (100 key indicators) quick lookup. Covers statistics-table discovery, item-code lookup, time-series data retrieval, terminology glossary, and metadata lookup. Requires ECOS_API_KEY environment variable; a public demo key (`sample`) works for smoke tests capped at 10 rows per request.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- k-ecos
- owner
- public-data-analyst
- scope
- common
- status
- active
- version
- 1.0.1
- metadata
- { "type": "domain", "locale": "ko-KR", "source": "https://ecos.bok.or.kr", "license": "ECOS Open API terms (`경제통계 Open API 이용약관`)", "category": "financial-statistics", "triggers": [ "k-ecos", "/k-ecos", "ECOS", "`한국은행`", "`한국은행 Open API`", "`경제통계시스템`", "`기준금리`", "`환율`", "`본원통화`", "`100대 통계지표`", "Bank of Korea statistics", "Korean monetary statistics" ] }
- relates_to
- [ { "type": "composes_with", "skill": "k-dart" }, { "type": "composes_with", "skill": "k-kosis" }, { "type": "composes_with", "skill": "k-opendata" } ]
- description
- Queries the Bank of Korea Economic Statistics System (`한국은행 경제통계시스템 ECOS`) Open API for Korean macro-financial statistics — base rate, exchange rates, money supply, interest rates, GDP, and the `100대 통계지표` (100 key indicators) quick lookup. Covers statistics-table discovery, item-code lookup, time-series data retrieval, terminology glossary, and metadata lookup. Requires ECOS_API_KEY environment variable; a public demo key (`sample`) works for smoke tests capped at 10 rows per request.
- l2_propagate
- true
- last_reviewed
- 1789084800000
- prerequisites
- ECOS_API_KEY environment variable (public demo key `sample` usable for ≤10-row queries)
02 资源文件 3
- 参考文档references/terms-ko.json4.8 KB
- 脚本scripts/ecos-fetch.ts10.4 KB
- 脚本scripts/verify-terms.ts5.0 KB
03 SKILL.md 正文
Context
Unified skill for the Bank of Korea (BOK, 한국은행) Economic Statistics System (ECOS, 경제통계시스템) Open API — covers statistics-table discovery, item-code lookup, time-series data retrieval, the 100대 통계지표 (100 key indicators) latest-value snapshot, statistical terminology glossary, and metadata lookup. ECOS is the authoritative primary source for Korean monetary and financial statistics (base rate, market rates, exchange rates, money supply/liquidity, credit, household finances) that KOSIS (k-kosis) mostly re-publishes secondhand. Complements DART-based company financials (k-dart) and public-portal trade data (k-opendata): ECOS supplies the central-bank-grade macro-financial series needed to frame a company or market narrative against Korean monetary conditions. Useful for pitch-deck research requiring verified BOK statistics with citation.
When to Use
- Time-series retrieval for a known BOK statistic (e.g., "get
한국은행 기준금리monthly 2020–2024") - Finding the right ECOS table/series by browsing the statistics tree ("
기준금리 관련 통계표 찾아줘") - Latest-value snapshot of headline indicators via the
100대 통계지표(exchange rates, growth rate, income) — fastest path for a single number - Item-structure lookup for a table (item codes, units, available cycles, data coverage)
- Statistical terminology lookup ("what does
소비자동향지수mean, per BOK") - Macro-financial context research to support market-sizing or monetary-condition slides
- Any engagement requiring verified Bank of Korea statistics with citation
Execution Steps
Prefer the bundled helper scripts/ecos-fetch.ts (see Helper Script) for retrieval steps — it handles encoding, pagination, retry, and error normalization; the raw requests below are the fallback.
- Verify Prerequisites: Confirm
ECOS_API_KEYenvironment variable is set. If not, either use the public demo keysample(works for all six services, capped at 10 rows per request — enough for smoke tests and theKeyStatisticListquick lookup) or guide the user to https://ecos.bok.or.kr ("MyPage→인증키 신청") to apply for a personal key. - Discover the target table: If the user only knows a statistic by name (not
통계표코드/STAT_CODE), browseStatisticTableList(서비스 통계 목록) — it returns the hierarchical category tree (STAT_NAMEvalues like1.1.1. 본원통화) where searchable leaves carrySRCH_YN=Y. There is no keyword-search endpoint; locate the table by category navigation or from the ECOS web UI (https://ecos.bok.or.kr →통계검색shows each table's통계표코드in its URL/meta). - Resolve item codes: Call
StatisticItemList(통계 세부항목 목록) with the table code to getITEM_CODE/ITEM_NAME,GRP_CODE(item group = filter dimension), per-cycle availability (CYCLE,START_TIME~END_TIME,DATA_CNT), andUNIT_NAME. Use this to pick the cycle and item codes instead of guessing. - Retrieve data: Call
StatisticSearch(통계 조회 조건 설정) with the table code, cycle (A/S/Q/M/SM/D— neverYY/QQ/MM/DD), cycle-matching date formats, and optional item codes. Pass요청시작건수/요청종료건수to page through large result sets (1-based row range;list_total_countreports the full total). - Quick lookup (optional): For headline numbers ("
지금 원달러 환율?", "경제성장률?"), callKeyStatisticList(100대 통계지표) first — no parameters beyond counts, returns the latest value/classification/unit for each of the ~101 key indicators. - Glossary/metadata (optional): Call
StatisticWord(통계용어사전) with a term, orStatisticMeta(통계메타DB) with a data name, for BOK's official explanation. Percent-encode Korean path segments. - Process Response: Always pass
jsonas the요청유형. A successful response is{"<ServiceName>":{"list_total_count":N,"row":[...]}}; an error is a bare{"RESULT":{"CODE":"...","MESSAGE":"..."}}— treat any response withRESULTand norowas an error and surfaceCODE+MESSAGEverbatim. - Format Output: Present rows sorted by
TIME; pairDATA_VALUEwithUNIT_NAME; keep original figures. - Save to Deliverables: Store research findings in
deliverables/research/per project conventions; append disclaimer "한국은행 경제통계시스템 ECOS Open API 자료 기준 (조회: YYYY-MM-DD)" with the actual retrieval date.
Output Format
- Table discovery:
P_STAT_CODE/STAT_CODE/STAT_NAME/CYCLE/SRCH_YN(category tree navigation) - Item lookup:
GRP_NAME/ITEM_CODE/ITEM_NAME/CYCLE/START_TIME~END_TIME/DATA_CNT/UNIT_NAME - Statistical data:
STAT_NAME/ITEM_NAME1~ITEM_NAME4/UNIT_NAME/TIME/DATA_VALUE(the value), sorted by period - 100 key indicators:
CLASS_NAME/KEYSTAT_NAME/DATA_VALUE/CYCLE(latest period) /UNIT_NAME - Glossary:
WORD/CONTENTverbatim - Metadata:
LVL/CONT_NAME/META_DATA
Reference Material
references/terms-ko.json— Korean-term → ECOS code mapping (service names, cycle codes, verified starter tables, glossary). Keep SKILL.md English; look up Korean terms there.- Starter table codes, live-verified 2026-09-11 (codes may change — always confirm coverage via
StatisticItemList):722Y001(한국은행 기준금리 및 여수신금리; item0101000한국은행 기준금리, cycles A/Q/M/D),200Y101(주요지표(연간지표)— e.g. item10101국내총생산(명목, 원화표시)),102Y004(본원통화 구성내역(평잔, 원계열)— official-guide sample data). - If recurring lookups reveal stable table/item patterns, add them to
references/terms-ko.jsonrather than this file.
Related Skills
- k-dart
- k-kosis
- k-opendata
- research
ECOS Open API Specification
Prerequisites
ECOS_API_KEY environment variable. Sign up and apply at https://ecos.bok.or.kr ("MyPage → 인증키 신청"; registration is on the Open API portal, not the main ECOS statistics site).
The literal demo key sample is accepted by all six services for read-only testing, capped at 10 rows per request (exceeding it returns ERROR-301). Prefer it for smoke tests and KeyStatisticList lookups; use a personal key for real data pulls.
Request URL Format
All services use one positional path-parameter template (https and http both accepted per the official guide):
https://ecos.bok.or.kr/api/{서비스명}/{인증키}/{요청유형}/{언어구분}/{...service-specific segments}
Common leading segments:
| # | Segment | Values | Notes |
|---|---|---|---|
| 1 | 서비스명 |
see below | English service name (e.g. StatisticSearch) |
| 2 | 인증키 |
issued key or sample |
|
| 3 | 요청유형 |
json | xml |
always pass explicitly |
| 4 | 언어구분 |
kr | en |
en returns translated names/units |
Cycle Codes and Date Formats
StatisticSearch cycle segment (주기) — not YY/QQ/MM/DD; the wrong alphabet is the most common cause of ERROR-100:
| Cycle | Meaning | Date format (검색시작일자 / 검색종료일자) |
|---|---|---|
A |
연 (annual) |
2024 |
S |
반년 (semi-annual) |
2024S1 / 2024S2 (live-verified 2026-09-11) |
Q |
분기 (quarterly) |
2024Q1 |
M |
월 (monthly) |
202401 |
SM |
반월 (semi-monthly) |
202401S1 / 202401S2 — month + half index (live-verified 2026-09-11) |
D |
일 (daily) |
20240101 |
Verified-format examples: S → table 105Y001 (예금규모별 계좌수 및 금액), SM → table 814Y002 (예금은행 지급준비액(구기준, 평잔), data ends 2008). When unsure of a table's cycles and coverage, read CYCLE/START_TIME/END_TIME from StatisticItemList first — the START_TIME/END_TIME values themselves show the exact date format for that cycle. The date format must match the cycle exactly, otherwise ERROR-101 (주기와 다른 형식의 날짜 형식입니다).
1. StatisticSearch (통계 조회 조건 설정) — main data endpoint
GET https://ecos.bok.or.kr/api/StatisticSearch/{인증키}/{요청유형}/{언어}/{요청시작건수}/{요청종료건수}/{통계표코드}/{주기}/{검색시작일자}/{검색종료일자}/{통계항목코드1}/{통계항목코드2}/{통계항목코드3}/{통계항목코드4}
| Segment | Required | Description |
|---|---|---|
요청시작건수/요청종료건수 |
Y | 1-based row range of the full result (guide sample: 1/10); page through via list_total_count |
통계표코드 |
Y | e.g. 722Y001 |
주기 |
Y | A/S/Q/M/SM/D |
검색시작일자/검색종료일자 |
Y | cycle-matching format |
통계항목코드1~4 |
N | item path (1–4 levels). Omit to receive all items of the table |
Response row fields: STAT_CODE, STAT_NAME, ITEM_CODE1~4, ITEM_NAME1~4, UNIT_NAME, WGT, TIME, DATA_VALUE.
2. StatisticTableList (서비스 통계 목록) — category tree
GET https://ecos.bok.or.kr/api/StatisticTableList/{인증키}/{요청유형}/{언어}/{요청시작건수}/{요청종료건수}/{통계표코드}
| Segment | Required | Description |
|---|---|---|
통계표코드 |
N | filters to one table when given |
Response row fields: P_STAT_CODE, STAT_CODE, STAT_NAME, CYCLE, SRCH_YN, ORG_NAME. Navigate the hierarchy via P_STAT_CODE → STAT_CODE; leaves with SRCH_YN=Y are queryable in StatisticSearch.
3. StatisticItemList (통계 세부항목 목록) — item codes per table
GET https://ecos.bok.or.kr/api/StatisticItemList/{인증키}/{요청유형}/{언어}/{요청시작건수}/{요청종료건수}/{통계표코드}
Response row fields: STAT_CODE, STAT_NAME, GRP_CODE, GRP_NAME, ITEM_CODE, ITEM_NAME, P_ITEM_CODE, P_ITEM_NAME, CYCLE, START_TIME, END_TIME, DATA_CNT, UNIT_NAME, WEIGHT. GRP_NAME names the filter dimension (계정항목, 지역코드, …); item codes are passed to StatisticSearch in group order.
4. KeyStatisticList (100대 통계지표) — latest headline values
GET https://ecos.bok.or.kr/api/KeyStatisticList/{인증키}/{요청유형}/{언어}/{요청시작건수}/{요청종료건수}
No service-specific segments. ~101 rows; response row fields: CLASS_NAME, KEYSTAT_NAME, DATA_VALUE, CYCLE (latest period), UNIT_NAME. Best first stop for "current" values (환율, 경제성장률, 기준금리, 가구소득, …).
5. StatisticWord (통계용어사전) — glossary
GET https://ecos.bok.or.kr/api/StatisticWord/{인증키}/{요청유형}/{언어}/{요청시작건수}/{요청종료건수}/{용어}
| Segment | Required | Description |
|---|---|---|
용어 |
Y | Korean term (e.g. 소비자동향지수) — percent-encode |
Response row fields: WORD, CONTENT (BOK's official explanation, up to 4000 chars).
6. StatisticMeta (통계메타DB) — metadata
GET https://ecos.bok.or.kr/api/StatisticMeta/{인증키}/{요청유형}/{언어}/{요청시작건수}/{요청종료건수}/{데이터명}
| Segment | Required | Description |
|---|---|---|
데이터명 |
Y | Korean data name (e.g. 경제심리지수) — percent-encode |
Response row fields: LVL, P_CONT_CODE, CONT_CODE, CONT_NAME, META_DATA.
Quick Recipes (verified 2026-09-11)
# 1) Latest headline values (환율/성장률/기준금리/…): page with a personal key,
# or 1/10 windows with the sample key
curl -fsS 'https://ecos.bok.or.kr/api/KeyStatisticList/'"$ECOS_API_KEY"'/json/kr/1/101/'
# → filter rows client-side by CLASS_NAME/KEYSTAT_NAME; CYCLE holds the latest period
# 2) BOK base rate, most recent 12 months (item 0101000 = 한국은행 기준금리)
curl -fsS 'https://ecos.bok.or.kr/api/StatisticSearch/'"$ECOS_API_KEY"'/json/kr/1/12/722Y001/M/202509/202608/0101000/'
# 3) Annual nominal GDP (200Y101 주요지표(연간지표), item 10101 = 국내총생산(명목))
curl -fsS 'https://ecos.bok.or.kr/api/StatisticSearch/'"$ECOS_API_KEY"'/json/kr/1/10/200Y101/A/2020/2025/10101/'
All three return the standard success envelope; recipe 1 works with the sample key only in 10-row windows.
Helper Script
scripts/ecos-fetch.ts (self-contained, bun) wraps everything in this section — Korean path-segment encoding, 1-based row-range pagination (respecting the sample key's ≤10-row windows), exponential backoff on ERROR-602/HTTP 5xx, and error-envelope normalization. Prefer it over hand-rolled curl; the raw requests above are the no-tooling fallback.
# BOK base rate, monthly, most recent 12 months → markdown table
bun scripts/ecos-fetch.ts --service StatisticSearch --table 722Y001 --cycle M \
--from 202509 --to 202608 --items 0101000 --format md --sample
# Latest key indicators (auto-pages the sample-key cap)
bun scripts/ecos-fetch.ts --service KeyStatisticList --sample --format md
scripts/verify-terms.ts re-validates the codes in references/terms-ko.json against the live API (drift check — run it before trusting recorded codes, and refresh the file's verified date when it passes):
bun scripts/verify-terms.ts # uses the sample key; --include-unverified to check all entries
Example Requests
# Latest headline values — 100 key indicators (works with the `sample` key)
curl -fsS --get 'https://ecos.bok.or.kr/api/KeyStatisticList/sample/json/kr/0/10/'
# BOK base rate, monthly 2021, item 0101000 (한국은행 기준금리)
curl -fsS 'https://ecos.bok.or.kr/api/StatisticSearch/'"$ECOS_API_KEY"'/json/kr/1/12/722Y001/M/202101/202112/0101000/'
# Same query without item codes — returns ALL items of the table for the period
curl -fsS 'https://ecos.bok.or.kr/api/StatisticSearch/'"$ECOS_API_KEY"'/json/kr/1/10/722Y001/M/202601/202608/'
# Annual GDP (명목) from the guide's example table 200Y101, item 10101
curl -fsS 'https://ecos.bok.or.kr/api/StatisticSearch/'"$ECOS_API_KEY"'/json/kr/1/10/200Y101/A/2020/2023/10101/'
# Browse the category tree (839 nodes as of 2026-09-11)
curl -fsS 'https://ecos.bok.or.kr/api/StatisticTableList/'"$ECOS_API_KEY"'/json/kr/1/10/'
# Item codes / coverage of a table
curl -fsS 'https://ecos.bok.or.kr/api/StatisticItemList/'"$ECOS_API_KEY"'/json/kr/1/10/722Y001'
# Glossary lookup — percent-encode the Korean term
WORD=$(python3 -c "import urllib.parse; print(urllib.parse.quote('소비자동향지수'))")
curl -fsS 'https://ecos.bok.or.kr/api/StatisticWord/'"$ECOS_API_KEY"'/json/kr/1/10/'"$WORD"'/'
Response Shape / Response Policy
Verified by live testing (2026-09-11) — all six services respond correctly with the sample key:
- Success: a single JSON object keyed by the service name, e.g.
{"StatisticSearch":{"list_total_count":12,"row":[{...}, ...]}}(KeyStatisticListadditionally carriesrow_count). Iteraterow; uselist_total_countfor pagination. - Error: a bare object
{"RESULT":{"CODE":"...","MESSAGE":"..."}}with norowkey — surfaceCODE+MESSAGEverbatim. Note the guide lists codes as정보-100/에러-301etc., but the JSON payload spells themINFO-100/ERROR-301. - Cycle-code alphabet gotcha: the widely-copied tutorials use
YY/QQ/MM/DD; the live API returnsERROR-100for those. OnlyA/S/Q/M/SM/Dare accepted (official guide + verified live). - Row-range segments are 1-based (official sample
1/10). Thesample-key cap applies to the window span:요청종료건수 − 요청시작건수 < 10, i.e. at most 10 rows per window starting at ≥1 — verified live (1/10and11/20pass;0/10failsERROR-301even though0/5passes, so a leading0is only safe for tiny windows). With a personal key the span cap is much larger; page in comfortable windows vialist_total_count. - Omitting all item codes returns every item in the table for the date range — convenient but can be large; filter client-side or narrow the item path.
- Korean path segments (
용어,데이터명) must be percent-encoded; a literal UTF-8 Korean path segment was observed to 404 at the CDN level. DATA_VALUEis returned as a string; keep the original string in deliverables and format for display only.- Append disclaimer at the end: "
한국은행 경제통계시스템 ECOS Open API 자료 기준 (조회: YYYY-MM-DD)" with the actual retrieval date.
Failure Modes
| Code | Meaning (verbatim source) | Action |
|---|---|---|
INFO-100 |
인증키가 유효하지 않습니다 |
Check ECOS_API_KEY; sample only works with ≤10-row ranges |
INFO-200 |
해당하는 데이터가 없습니다 |
No data for the table/cycle/dates — verify coverage via StatisticItemList |
ERROR-100 |
필수 값이 누락되어 있습니다 |
Usually a wrong cycle code (MM vs M) or malformed dates — re-check the segment order |
ERROR-101 |
주기와 다른 형식의 날짜 형식입니다 |
Date format doesn't match the cycle (2024 for A, 2024Q1 for Q, 202401 for M, 20240101 for D) |
ERROR-200 |
파일타입 값이 누락 혹은 유효하지 않습니다 |
Use json or xml |
ERROR-300/ERROR-301 |
조회건수 값이 누락/타입이 유효하지 않습니다 |
Row range missing or non-integer; with sample, also fires above 10 rows |
ERROR-400 |
검색범위가 적정범위를 초과하여 60초 TIMEOUT |
Narrow the date range or item path and retry |
ERROR-500 |
서버 오류 / 해당 서비스를 찾을 수 없습니다 |
Check the service name spelling |
ERROR-600/ERROR-601 |
DB Connection / SQL 오류 |
Transient server-side fault — retry later |
ERROR-602 |
과도한 OpenAPI호출로 이용이 제한되었습니다 |
Rate-limited — back off and retry after a wait |
Notes
- Data source: 한국은행 경제통계시스템 ECOS Open API — official developer guide at
개발가이드→개발 명세서(SPA; each service's spec page has a개발명세서 다운로드button). - This skill is read-only query only.
- License/terms:
경제통계 Open API 이용약관— cite "출처: 한국은행 경제통계시스템" plus the retrieval date when reproducing figures in deliverables. Per-consumer daily/hourly quotas are not publicly documented; onlyERROR-602signals throttling. - ECOS is the primary source for monetary/financial statistics; KOSIS (
k-kosis) re-publishes some of the same series — prefer ECOS for BOK-originated series and for English-language BOK names via언어구분=en. - All endpoint shapes, the cycle-code alphabet, the
samplekey behavior, and every error code table row above were verified against the live API and the official SPA guide on 2026-09-11.
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.