| name | bok-ecos-stats |
| description | 한국은행 ECOS Open API로 기준금리, 환율, 소비자물가지수, 통화량 등 중앙은행 경제통계 시계열과 100대 핵심지표를 조회한다. Use when the user asks 기준금리, 환율 추이, 물가지수, M2, 국고채 금리, 거시경제 통계. Not for 주식 시세(korean-stock-search) or KOSIS 일반 통계(kosis-stats). |
| license | MIT |
| metadata | {"category":"data","locale":"ko-KR","phase":"v1"} |
한국은행 ECOS 경제통계 조회
What this skill does
한국은행 경제통계시스템(ECOS) Open API https://ecos.bok.or.kr/api/ 로 중앙은행 경제통계를 조회한다.
search — 통계코드(또는 alias) 기반 시계열 데이터 조회tables — 통계표 카탈로그 목록items — 특정 통계표의 항목(item) 목록key — 100대 핵심지표 (환율/금리/물가/국민소득 등 최신값)word — 통계 용어 사전 검색
조회 전용이다. 투자 판단·전망 단정은 범위 밖이다.
When to use
- "지금 한국은행 기준금리 몇 %야?"
- "최근 원달러 환율 추이 보여줘"
- "소비자물가지수 월별로 뽑아줘"
- "M2 통화량 통계 찾아줘"
- "ECOS에서 국고채 3년 금리 조회해줘"
When not to use
- 주식/증권 시세 →
korean-stock-search, toss-securities
- KOSIS 일반 통계(인구/가구/고용 등) →
kosis-stats
- 환전 수수료·실시간 매매 환율 비교 (ECOS는 공식 통계 기준)
Prerequisites
- Python 3.9+ (stdlib only, 외부 패키지 없음)
- 사용자 API 키 불필요 — ECOS 공개 데모 키(
sample)로 무가입 동작 확인 (2026-07-21). 단 호출당 최대 10행 제한이 있다. 공개 엔드포인트이므로 k-skill-proxy를 경유하지 않고 직접 호출한다.
선택 환경변수 (더 많은 행이 필요할 때):
Workflow
1. 자주 쓰는 지표는 alias로 바로 조회
python3 bok-ecos-stats/scripts/bok_ecos.py search --alias 기준금리 --start 20260101 --end 20260721 --text
python3 bok-ecos-stats/scripts/bok_ecos.py search --alias 원달러환율 --start 20260701 --end 20260721 --text
python3 bok-ecos-stats/scripts/bok_ecos.py search --alias 소비자물가지수 --start 202501 --end 202606 --text
지원 alias: 기준금리, 원달러환율, 소비자물가지수(=cpi), M2(=통화량), 국고채3년.
--start/--end는 주기 형식을 따른다: 일(D) YYYYMMDD, 월(M) YYYYMM, 분기(Q) YYYYQn, 연(A) YYYY.
2. 최신 핵심지표 한 번에 보기
python3 bok-ecos-stats/scripts/bok_ecos.py key --limit 10 --text
3. 임의 통계표 탐색 → 항목 확인 → 시계열 조회
python3 bok-ecos-stats/scripts/bok_ecos.py tables --text
python3 bok-ecos-stats/scripts/bok_ecos.py items --stat-code 722Y001 --text
python3 bok-ecos-stats/scripts/bok_ecos.py search --stat-code 722Y001 --cycle D \
--start 20260101 --end 20260721 --item-code 0101000 --text
4. 용어가 낯설면 사전 검색
python3 bok-ecos-stats/scripts/bok_ecos.py word --query 소비자물가지수 --text
--text 없이 실행하면 구조화 JSON(result, rows, source)을 출력한다.
Data source
https://ecos.bok.or.kr/api/<Service>/<key>/json/kr/<start>/<end>/<segments...> — 쿼리스트링 없는 positional URL. 한글 검색어는 helper가 percent-encoding 처리한다.- 데모 키
sample: 무가입, 호출당 최대 10행 (초과 시 ERROR-301).
- 잘못된 키: HTTP 200 +
{"RESULT":{"CODE":"INFO-100"}}.
- 빈 결과:
{"RESULT":{"CODE":"INFO-200","MESSAGE":"해당하는 데이터가 없습니다."}} → result: "empty".
Failure modes
| 상황 | 동작 |
|---|
빈 결과 (INFO-200) | result: "empty" — 기간/코드 확인 안내 |
인증키 오류 (INFO-100) | 개인 키 발급/확인 안내 |
sample 10행 초과 (ERROR-301) | 개인 키 발급 안내 (helper는 sample 사용 시 limit을 10으로 자동 캡) |
| 알 수 없는 alias, stat-code 없는 search | upstream 미호출, 사용법 오류 출력 |
| HTTP 오류/타임아웃/JSON 파싱 실패 | 차단·점검 가능성 안내 후 종료 코드 1 |
Notes
- 시계열 값은 공식 통계 원천 그대로 전달하고, 해석·전망은 덧붙이지 않는다.
- 통계 기준 시점(
time)을 반드시 함께 표시한다.
