nomadamas__k-skill/docs/features/bok-ecos-stats.md

한국은행 ECOS 경제통계 조회

bok-ecos-stats는 한국은행 ECOS Open API로 기준금리·환율·물가·통화량 등 중앙은행 경제통계를 조회하는 stdlib Python helper다.

기본 경로

• GET https://ecos.bok.or.kr/api/<Service>/<key>/json/kr/<start>/<end>/<segments...> — positional URL, 쿼리스트링 없음
• 서비스: StatisticSearch(시계열), StatisticTableList(카탈로그), StatisticItemList(항목), KeyStatisticList(100대 지표), StatisticWord(용어사전)

공개 데모 키 sample로 무가입 동작한다 (2026-07-21 확인, 호출당 최대 10행). 공개 엔드포인트이므로 k-skill-proxy를 경유하지 않는다. 더 많은 행이 필요하면 https://ecos.bok.or.kr/api 에서 무료 키를 발급받아 KSKILL_BOK_ECOS_API_KEY 환경변수(또는 ~/.config/k-skill/secrets.env)로 지정한다.

사용 예시

# 기준금리 시계열
npx -y @nomadamas/k-skill@0 exec bok-ecos-stats scripts/bok_ecos.py -- search --alias 기준금리 --start 20260101 --end 20260721 --text

# 최신 핵심지표 (환율/금리/물가)
npx -y @nomadamas/k-skill@0 exec bok-ecos-stats scripts/bok_ecos.py -- key --limit 10 --text

# 통계표 탐색 → 항목 → 시계열
npx -y @nomadamas/k-skill@0 exec bok-ecos-stats scripts/bok_ecos.py -- tables --text
npx -y @nomadamas/k-skill@0 exec bok-ecos-stats scripts/bok_ecos.py -- items --stat-code 722Y001 --text
npx -y @nomadamas/k-skill@0 exec bok-ecos-stats scripts/bok_ecos.py -- search --stat-code 722Y001 --cycle D --start 20260101 --end 20260721 --item-code 0101000

허용 입력

입력	적용	제한
--alias	search	기준금리/원달러환율/소비자물가지수/M2/국고채3년
--stat-code	search/items	영숫자·_.-만 허용 (URL 세그먼트 검증)
--cycle	search	A/S/Q/M/SM/D
--start/--end	search	주기 형식 (D=YYYYMMDD, M=YYYYMM, A=YYYY)
--limit	공통	기본 10, sample 키 사용 시 10으로 자동 캡
--query	word	한글 검색어 percent-encoding 자동 처리

실패 처리

• INFO-100 (인증키 오류): typed 오류 + 키 발급 안내
• INFO-200 (데이터 없음): result: "empty"로 명시
• ERROR-301 (sample 10행 초과): 개인 키 발급 안내
• 경로 세그먼트 침입 문자(/ 등): upstream 미호출, 검증 오류
• HTTP 오류/타임아웃/비JSON 응답: 차단·점검 가능성 안내 후 종료 코드 1