ecos-enhanced 0.1.0

Async Python client for Bank of Korea ECOS (Economic Statistics System) API

ecos-enhanced

Async Python client for Bank of Korea ECOS API

한국은행 경제통계시스템(ECOS) API를 위한 비동기 Python 클라이언트. 기준금리, 환율, 국고채 금리, 소비자물가지수, GDP 등 주요 경제 지표를 간편하게 조회합니다.

Features

• Async-first — httpx 기반 비동기 HTTP 클라이언트
• Built-in registry — 12개 주요 통계코드 내장 (금리, 환율, 물가, GDP 등)
• Convenience methods — get_base_rate(), get_exchange_rate() 등 원라인 조회
• Zero pandas dependency — 순수 Python dataclass
• Fully typed — py.typed 마커, 모든 공개 API에 타입 힌트

Installation

pip install ecos-enhanced

Quick Start

import asyncio
from ecos_enhanced import EcosClient

async def main():
    async with EcosClient(api_key="YOUR_ECOS_API_KEY") as client:
        # 원/달러 환율
        rates = await client.get_exchange_rate("usd", "20240101", "20241231")
        for r in rates:
            print(f"{r.time}: {r.value}원")

        # 한국은행 기준금리
        base = await client.get_base_rate("202401", "202412")
        print(f"현재 기준금리: {base[-1].value}%")

        # 소비자물가지수
        cpi = await client.get_cpi("202401", "202412")
        print(f"최근 CPI: {cpi[-1].value}")

asyncio.run(main())

Error Handling

from ecos_enhanced import EcosClient, EcosApiError

async with EcosClient() as client:
    try:
        data = await client.get_by_key("usd_krw", "20240101", "20241231")
    except EcosApiError as e:
        print(f"ECOS API 오류: {e} (code={e.code})")

API Reference

EcosClient

client = EcosClient(api_key="...")  # 또는 환경변수 ECOS_API_KEY

Method	Description
get_statistic(stat_code, cycle, start_date, end_date, item_code)	범용 통계 조회
get_by_key(key, start_date, end_date)	레지스트리 키로 간편 조회
get_base_rate(start_date, end_date)	한국은행 기준금리
get_exchange_rate(currency, start_date, end_date)	환율 (usd, jpy, eur, cny)
get_cpi(start_date, end_date)	소비자물가지수
get_treasury_yield(maturity, start_date, end_date)	국고채 금리 (3y, 10y)
get_gdp(start_date, end_date)	실질 GDP (분기)
get_available_keys()	사용 가능한 레지스트리 키 목록
close()	HTTP 클라이언트 종료 (context manager 사용 시 자동 호출)

EcosDataPoint

모든 조회 메서드의 반환 타입 (리스트):

Field	Type	Description
stat_code	str	통계표 코드
stat_name	str	통계표 이름
item_name	str	통계항목 이름
time	str	시점 (YYYYMMDD 또는 YYYYMM)
value	float	데이터 값
unit	str	단위

Built-in Registry (STAT_CODES)

Key	Name	Cycle	Unit
base_rate	한국은행 기준금리	M	연%
cd_rate	CD(91일) 금리	D	연%
treasury_3y	국고채(3년) 금리	D	연%
treasury_10y	국고채(10년) 금리	D	연%
usd_krw	원/달러 환율(종가)	D	원
jpy_krw	원/100엔 환율(종가)	D	원
eur_krw	원/유로 환율(종가)	D	원
cny_krw	원/위안 환율(종가)	D	원
cpi	소비자물가지수(총지수)	M	2020=100
m2	M2(광의통화)	M	십억원
gdp	실질 국내총생산(GDP)	Q	십억원

레지스트리에 없는 통계는 get_statistic()으로 직접 조회할 수 있습니다.

Date Format

Cycle	Format	Example
D (일)	YYYYMMDD	"20240315"
M (월)	YYYYMM	"202403"
Q (분기)	YYYYQ	"2024Q1"
A (연)	YYYY	"2024"

Environment Variables

Variable	Description
ECOS_API_KEY	ECOS API 인증키 (발급)

ECOS API Key

1. ECOS API 접속
2. 회원가입 후 "인증키 신청"
3. 발급받은 키를 환경변수 ECOS_API_KEY로 설정하거나 EcosClient(api_key="...")에 전달

Important Notes

비동기 전용

이 라이브러리는 async/await 전용입니다. 동기 코드에서 사용하려면:

import asyncio
result = asyncio.run(main())

재무제표 파서 한계

• ECOS API는 통계표 코드 + 항목 코드 조합으로 데이터를 조회합니다.
• 내장 레지스트리(STAT_CODES)에 없는 통계는 ECOS API 문서에서 코드를 확인한 후 get_statistic()으로 직접 조회하세요.

Disclaimer

이 라이브러리는 한국은행 ECOS API 데이터 조회를 위한 기술적 도구이며, 투자 권유 또는 금융 서비스를 제공하지 않습니다. 데이터 활용 시 ECOS API 이용약관 및 관련 법규를 준수할 책임은 사용자에게 있습니다.

This library is a technical tool for querying the Bank of Korea ECOS API and does not provide investment advice or financial services.

License

MIT License. See LICENSE.