ecos-reader

한국은행 ECOS Open API Python 클라이언트

한국은행 ECOS Open API를 Python에서 쉽고 일관된 방식으로 사용할 수 있는 라이브러리입니다.

설치

pip install ecos-reader

또는 개발 버전 설치:

git clone https://github.com/choo121600/ecos-reader.git
cd ecos-reader
pip install -e ".[dev]"

API 키 설정

ECOS API를 사용하려면 한국은행에서 발급받은 API 키가 필요합니다.

API 키 신청하기

방법 1: 환경 변수 (권장)

export ECOS_API_KEY="your_api_key"

또는 .env 파일 생성:

ECOS_API_KEY=your_api_key

참고: v0.1.0부터는 라이브러리 import 시점에 .env를 자동으로 로드하지 않습니다. .env를 사용하려면 아래처럼 ecos.load_env()를 한 번 호출하세요.

import ecos

ecos.load_env()  # .env 로드 (명시적)

방법 2: 코드에서 직접 설정

import ecos

ecos.set_api_key("your_api_key")

빠른 시작

import ecos

# 한국은행 기준금리 조회
df = ecos.get_base_rate()
print(df)
#         date  value unit
# 0 2024-01-01   3.50    %
# 1 2024-02-01   3.50    %
# ...

# 소비자물가지수(CPI) 조회
df = ecos.get_cpi(start_date="202301", end_date="202312")
print(df)

# 국고채 수익률 조회
df = ecos.get_treasury_yield(maturity="10Y")
print(df)

# GDP 조회
df = ecos.get_gdp(frequency="quarterly", basis="real")
print(df)

두 가지 사용 방식

ecos-reader는 동등한 두 진입점을 제공하며, 둘 다 정규화된 long-format DataFrame을 반환합니다.

	큐레이션 함수	범용 조회
함수	`get_base_rate()`, `get_cpi()`, `get_gdp()` … (37개)	`get_series(stat_code, period, …)`
언제	자주 쓰는 고가치 지표를 검증된 인자로 바로	ECOS의 어떤 통계표든 직접
탐색	함수 시그니처가 곧 옵션	`search_tables()` / `list_tables()` / `list_items()` (오프라인)
도달 범위	큐레이션된 핵심 지표	ECOS 전체 (도달 못 하는 통계 없음)

큐레이션 함수가 없는 통계는 get_series 로 직접 조회합니다. 통계표·항목은 네트워크 없이 동봉 카탈로그로 탐색합니다.

import ecos

# 1) 통계표 찾기 (오프라인 카탈로그 검색)
hits = ecos.search_tables("소비자물가")
print(hits[["stat_code", "stat_name", "cycle"]].head())

# 2) 임의 시계열 조회 — 윈도우 초과 시 자동 페이지네이션
df = ecos.get_series(
    "901Y009", "monthly",
    start_date="202401", end_date="202412",
    item_code="0",   # 생략 시 전체 항목
)

# 3) 표의 세부 항목(item_code) 탐색
items = ecos.list_items("901Y009")
print(items[["item_code", "item_name", "cycle"]].head())

큐레이션 함수는 범용 조회 위에 올바른 (stat_code, item_code, period)를 검증해 얹은 편의 계층입니다. 전체 흐름과 옵션은 범용 조회 & 탐색 가이드를 참고하세요.

지원 지표

금리 지표

함수	설명	주기
`get_base_rate()`	한국은행 기준금리	월
`get_treasury_yield(maturity)`	국고채 수익률 (1Y/3Y/5Y/10Y/20Y/30Y)	일
`get_yield_spread()`	장단기 금리차	일
`get_bank_deposit_rate(basis)`	예금은행 수신금리 (신규/잔액)	월
`get_bank_lending_rate(basis)`	예금은행 대출금리 (신규/잔액)	월

물가 지표

함수	설명	주기
`get_cpi()`	소비자물가지수 전년동월비	월
`get_core_cpi()`	근원 CPI (식료품·에너지 제외)	월
`get_ppi()`	생산자물가지수 전년동월비	월
`get_cpi_monthly(sub_category)`	CPI 월별 원지수 (품목·분류별)	월
`get_cpi_by_category(category)`	CPI 세부 항목별 지수 (상품/서비스 등 8종)	월

성장 지표

함수	설명	주기
`get_gdp(frequency, basis)`	GDP (분기/연간, 실질/명목)	분기/연
`get_gdp_deflator()`	GDP 디플레이터	분기/연
`get_gdp_growth_rate()`	실질 GDP 성장률	분기
`get_gdp_by_industry(basis, seasonal_adj)`	산업별 GDP (실질/명목, 계절조정/원계열)	분기/연
`get_gdp_by_expenditure(basis)`	지출항목별 GDP (실질/명목)	분기/연
`get_gdp_deflator_by_industry()`	산업별 GDP 디플레이터	분기/연

통화 지표

함수	설명	주기
`get_money_supply(indicator)`	통화량 (M1/M2/Lf)	월
`get_bank_lending(sector)`	예금은행 대출금 (전체/가계)	월
`get_m1_variants(variant)`	M1 세부 (평잔·말잔, 계절조정·원계열)	월
`get_m2_variants(variant)`	M2 세부 (평잔·말잔, 계절조정·원계열)	월
`get_m2_by_holder(variant)`	M2 경제주체별 (평잔·말잔, 계절조정·원계열)	월

가계금융 지표

함수	설명	주기
`get_household_credit(category)`	가계신용 (업권별/용도별)	분기
`get_household_lending_detail(sub_category)`	예금취급기관 가계대출 (용도별)	월
`get_borrower_loan(loan_type, category)`	차주별 가계대출 (신규/잔액)	분기

재정·금융시장 지표

함수	설명	주기
`get_fiscal_balance()`	통합재정수지	월
`get_stock_index(frequency, sub_category)`	주가지수 KOSPI (일별/월별)	일/월
`get_investor_trading(action, metric, sub_category)`	투자자별 주식거래	월
`get_bond_market(bond_type, measure, sub_category)`	채권 거래 (종류별/시장별)	월

실물경기 지표

함수	설명	주기
`get_industrial_production(seasonal)`	전산업생산지수 (원계열/계절조정)	월
`get_facility_investment(seasonal)`	설비투자지수 (원지수/계절조정)	월
`get_composite_index(index)`	경기종합지수 (선행/동행/후행)	월
`get_retail_sales(index, frequency)`	소매판매액지수 (불변/경상/계절조정)	월/분기/연

심리 지표

함수	설명	주기
`get_business_sentiment(sector)`	기업경기실사지수 BSI 업황전망 (전산업/제조/비제조)	월
`get_consumer_sentiment()`	소비자심리지수 (CCSI)	월

환율·국제수지·무역 지표

함수	설명	주기
`get_exchange_rate(currency)`	원/외화 매매기준율 (USD/JPY/EUR/CNY)	일
`get_balance_of_payments(account, frequency)`	국제수지 (경상/자본/금융계정)	월/분기/연
`get_trade(flow, frequency)`	수출입금액 통관기준 (수출/수입)	월/연

ℹ️ v0.3.0 이후 과거 단일 ECOS item만 반환하던 함수들이 전체 시리즈 long-format + sub_category 선택으로 재설계되었고, EcosPartialCoverageWarning은 제거되었습니다. 자세한 변경·마이그레이션은 마이그레이션 가이드를 참고하세요.

상세 사용법

기간 지정

# 월간 데이터 (YYYYMM 형식)
df = ecos.get_base_rate(start_date="202001", end_date="202312")

# 일간 데이터 (YYYYMMDD 형식)
df = ecos.get_treasury_yield(maturity="3Y", start_date="20240101", end_date="20241231")

# 분기 데이터 (YYYYQN 형식)
df = ecos.get_gdp(frequency="quarterly", start_date="2020Q1", end_date="2024Q4")

# 연간 데이터 (YYYY 형식)
df = ecos.get_gdp(frequency="annual", start_date="2015", end_date="2024")

고급 사용 예제

1. 통화정책 모니터링

import ecos
import matplotlib.pyplot as plt

# 기준금리와 CPI 동시 조회
base_rate = ecos.get_base_rate(start_date="202001", end_date="202412")
cpi = ecos.get_cpi(start_date="202001", end_date="202412")

# 그래프 그리기
fig, ax1 = plt.subplots(figsize=(12, 6))
ax1.plot(base_rate['date'], base_rate['value'], label='기준금리')
ax2 = ax1.twinx()
ax2.plot(cpi['date'], cpi['value'], color='red', label='CPI')
plt.title('통화정책 모니터링')
plt.show()

2. GDP 성장 분석

import ecos

# 실질 GDP 및 성장률 조회
gdp = ecos.get_gdp(frequency="quarterly", basis="real", start_date="2020Q1", end_date="2024Q4")
growth = ecos.get_gdp_growth_rate(frequency="quarterly", start_date="2020Q1", end_date="2024Q4")

# 산업별 기여도 분석
industry_gdp = ecos.get_gdp_by_industry(
    basis="real",
    seasonal_adj=True,
    frequency="quarterly",
    start_date="2023Q1",
    end_date="2023Q4"
)

3. 금융시장 대시보드

import ecos

# 주요 금융시장 지표 수집
stock = ecos.get_stock_index(frequency="daily", start_date="20240101", end_date="20241231")
bond = ecos.get_bond_market(bond_type="종류별", start_date="202401", end_date="202412")
investor = ecos.get_investor_trading(start_date="202401", end_date="202412")

print("주식시장:", len(stock), "rows")
print("채권시장:", len(bond), "rows")
print("투자자거래:", len(investor), "rows")

4. 가계부채 모니터링

import ecos

# 가계신용 및 대출 추이
credit = ecos.get_household_credit(category="업권별", start_date="2020Q1", end_date="2024Q4")
lending = ecos.get_household_lending_detail(start_date="202001", end_date="202412")
borrower = ecos.get_borrower_loan(loan_type="잔액", start_date="2023Q1", end_date="2024Q4")

# 가계대출 금리
rate = ecos.get_bank_lending_rate(basis="신규취급액", start_date="202301", end_date="202412")

캐시 관리

import ecos

# 캐시 비활성화 (실시간 데이터 필요 시)
ecos.disable_cache()

# 캐시 활성화 (기본값)
ecos.enable_cache()

# 캐시 초기화
ecos.clear_cache()

에러 처리

import ecos
from ecos import EcosAPIError, EcosConfigError, EcosNetworkError

try:
    df = ecos.get_base_rate()
except EcosConfigError as e:
    print(f"API 키 설정 오류: {e}")
except EcosNetworkError as e:
    print(f"네트워크 오류: {e}")
except EcosAPIError as e:
    print(f"API 오류 [{e.code}]: {e.message}")

로깅 활성화(선택)

라이브러리는 import 시점에 로깅 핸들러를 자동으로 구성하지 않습니다. 필요 시 아래처럼 활성화하세요.

import logging
import ecos

ecos.setup_logging(logging.INFO)

직접 클라이언트 사용

from ecos import EcosClient

# 클라이언트 생성
client = EcosClient(
    api_key="your_api_key",
    timeout=60,
    max_retries=5,
    use_cache=True,
)

# 통계 데이터 조회
response = client.get_statistic_search(
    stat_code="722Y001",
    period="M",
    start_date="202401",
    end_date="202412",
    item_code1="0101000",
)

# 통계표 목록 조회
tables = client.get_statistic_table_list(start=1, end=10)

# 통계 세부항목 조회
items = client.get_statistic_item_list(stat_code="200Y101")

# 통계용어사전 검색
word_result = client.get_statistic_word(word="소비자물가지수")

# 100대 통계지표 조회
key_stats = client.get_key_statistic_list(start=1, end=10)

# 통계 메타데이터 조회
meta = client.get_statistic_meta(data_name="경제심리지수")

테스트

pytest
pytest --cov=src/ecos  # 커버리지 포함

프로젝트 구조

ecos-reader/
├── src/ecos/
│   ├── access.py            # 범용 조회 (get_series, list_items)
│   ├── catalog.py           # 통계표 카탈로그 탐색 (오프라인)
│   ├── client.py            # API 클라이언트
│   ├── parser.py            # 응답 파서
│   ├── constants.py         # 통계코드 정의
│   ├── data/catalog.csv.gz  # 동봉 카탈로그 스냅샷
│   └── indicators/          # 큐레이션 지표 모듈
├── tests/                   # 테스트
├── docs/                    # 문서
└── examples/                # 예제

문서

전체 문서는 ecos-reader 공식 문서에서 확인할 수 있습니다.

로컬에서 문서 빌드

# 문서 도구 설치
pip install -e ".[docs]"

# 로컬 서버 실행
mkdocs serve

# 브라우저에서 http://127.0.0.1:8000 열기

프로젝트 문서

구현 현황: 2계층 커버리지 모델 — get_series로 ECOS 전체 도달 + 큐레이션 함수 37개. 동봉 카탈로그 834노드(검색가능 609개)
기여 가이드: 프로젝트 기여 방법
변경 이력: 버전별 변경사항

기여하기

ecos-reader는 오픈소스 프로젝트입니다. 기여를 환영합니다!

버그 리포트 및 기능 제안: GitHub Issues
코드 기여: 기여 가이드 참조
구현 현황: IMPLEMENTATION_STATUS.md에서 큐레이션 후보·커버리지 모델 확인

라이센스

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.

Name		Name	Last commit message	Last commit date
Latest commit History 109 Commits
.github		.github
docs		docs
examples		examples
public-api-docs		public-api-docs
scripts		scripts
src/ecos		src/ecos
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
API_SPEC.md		API_SPEC.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
IMPLEMENTATION_STATUS.md		IMPLEMENTATION_STATUS.md
LICENSE		LICENSE
README.md		README.md
ecos_all_statistics.csv		ecos_all_statistics.csv
ecos_implementation_status.csv		ecos_implementation_status.csv
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

ecos-reader

설치

API 키 설정

방법 1: 환경 변수 (권장)

방법 2: 코드에서 직접 설정

빠른 시작

두 가지 사용 방식

지원 지표

금리 지표

물가 지표

성장 지표

통화 지표

가계금융 지표

재정·금융시장 지표

실물경기 지표

심리 지표

환율·국제수지·무역 지표

상세 사용법

기간 지정

고급 사용 예제

1. 통화정책 모니터링

2. GDP 성장 분석

3. 금융시장 대시보드

4. 가계부채 모니터링

캐시 관리

에러 처리

로깅 활성화(선택)

직접 클라이언트 사용

테스트

프로젝트 구조

문서

로컬에서 문서 빌드

프로젝트 문서

기여하기

라이센스

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 17

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages