pyecos

pyecos

한국어 | English

한국은행 경제통계시스템 ECOS의 경제·금융 통계를 읽어옵니다.

기준금리와 시장금리, 환율, 통화량과 예금·대출, 코스피·코스닥, 소비자·생산자 물가, GDP와 성장률, 생산·소비·투자, 기업경기와 소비심리, 고용과 임금, 인구와 가계, 국제수지·외환보유액·대외채권채무, 수출입 물가·물량, 주택·토지 가격, 주요국(미·일·중·유로·영·한·캐나다·인도 등) 정책금리와 시장금리까지 다룹니다.

자주 쓰는 지표는 ecos.rate.base 같은 접근자로 바로 꺼내고, 그 밖의 통계는 통계표 코드로 조회합니다.

1. 설치

pip install pyecos

이 패키지는 ECOS API 키가 필요합니다. https://ecos.bok.or.kr/api/에서 무료로 발급받으세요. 발급하신 키를 넣는 방법은 다음과 같습니다.

방법 1 — 코드에서 직접 넣기 (바로 한 번 써볼 때)

from pyecos import ECOS

ecos = ECOS(api_key="발급받은-키")

방법 2 — 파일에 저장해서 계속 쓰기 (권장 — 한 번 저장하면 매번 안 넣어도 됩니다)

~/.config/pyecos/credentials.json 파일을 만들고 아래를 넣으세요.

{ "ECOS_API_KEY": "발급받은-키" }

그러면 이후로는 인자 없이 ECOS()만 써도 이 키를 자동으로 찾습니다.

환경변수를 선호하면, macOS·Linux는 터미널에서 export ECOS_API_KEY="발급받은-키", Windows는 PowerShell에서 setx ECOS_API_KEY "발급받은-키".

2. 빠른 시작

from pyecos import ECOS

ecos = ECOS()                                              # 저장해둔 키를 자동으로 찾습니다
rows = ecos.rate.base.fetch(start="202001", end="202412")  # 기준금리, 2020~2024년 월별
print(rows[:3])                                            # 앞의 3개만 찍어 확인

결과는 dict의 목록(list)이라, 표(DataFrame)로 한 줄에 바뀝니다. (pandas는 필수가 아닙니다.)

# pandas
import pandas as pd
pd.DataFrame(rows)

# polars
import polars as pl
pl.DataFrame(rows)

3. 큐레이션 지표 (149개)

통계표 코드를 외우지 않고, 자주 쓰는 지표를 ecos.그룹.지표 형태로 바로 꺼냅니다. 편집기에서 ecos. 뒤를 점(.)으로 타고 들어가면 자동완성으로 찾을 수 있고, 어느 지표든 두 가지를 제공합니다.

• .fetch(start, end) — 기간을 정해 시계열 전체를 가져옵니다
• .latest() — 가장 최근 값 하나만 가져옵니다

ecos.rate.base.fetch(start="202001", end="202412")  # 기준금리
ecos.fx.usd.latest()                                # 원/달러 최근값
ecos.trade.exports.semiconductor.value.fetch()      # 반도체 수출금액지수
ecos.price.producer.dram.fetch()                    # DRAM 생산자물가
ecos.price.producer.nand.fetch()                    # NAND플래시 생산자물가
ecos.stock.kospi.per.fetch()                        # 코스피 PER
ecos.world.rate.policy.us.latest()                  # 미국 정책금리 최근값

아래 트리에서 끝에 /가 붙은 줄은 묶음(예: rate/, stock/)일 뿐이고, /가 없는 줄이 실제 지표입니다. 지표 줄을 점으로 이어 부르면 됩니다 — 예: rate/ 안의 base → ecos.rate.base.

ecos
├── rate/
│   ├── base                              # 한국은행 기준금리
│   ├── call                              # 콜금리(익일물)
│   ├── koribor_3m                        # KORIBOR(3개월)
│   ├── cd_91d                            # CD수익률(91일)
│   ├── msb_364d                          # 통안증권수익률(364일)
│   ├── treasury_3y                       # 국고채수익률(3년)
│   ├── treasury_5y                       # 국고채수익률(5년)
│   ├── corporate_bond_3y                 # 회사채수익률(3년,AA-)
│   ├── deposit                           # 예금은행 수신금리
│   └── loan                              # 예금은행 대출금리
├── credit/
│   ├── total_deposits                    # 예금은행총예금(말잔)
│   ├── total_loans                       # 예금은행대출금(말잔)
│   ├── household_credit                  # 가계신용
│   └── household_delinquency_rate        # 가계대출연체율
├── money/
│   ├── m1                                # M1(협의통화, 평잔)
│   ├── m2                                # M2(광의통화, 평잔)
│   ├── lf                                # Lf(평잔)
│   └── l                                 # L(말잔)
├── fx/
│   ├── usd                               # 원/달러 환율(종가)
│   ├── jpy                               # 원/엔(100엔) 환율(매매기준율)
│   ├── eur                               # 원/유로 환율(매매기준율)
│   └── cny                               # 원/위안 환율(종가)
├── stock/
│   ├── kospi/
│   │   ├── index                         # 코스피지수
│   │   ├── trading_value                 # 주식거래대금(KOSPI)
│   │   ├── market_cap                    # 코스피 시가총액
│   │   ├── volume                        # 코스피 거래량
│   │   ├── turnover                      # 코스피 회전율
│   │   ├── dividend_yield                # 코스피 배당수익률
│   │   └── per                           # 코스피 PER
│   ├── kosdaq/
│   │   ├── index                         # 코스닥지수
│   │   ├── trading_value                 # 주식거래대금(KOSDAQ)
│   │   ├── market_cap                    # 코스닥 시가총액
│   │   ├── volume                        # 코스닥 거래량
│   │   └── turnover                      # 코스닥 회전율
│   └── investor_deposits                 # 투자자예탁금
├── bond/
│   ├── trading_value                     # 채권거래대금
│   └── treasury_issuance                 # 국고채발행액
├── growth/
│   ├── gdp_growth                        # 경제성장률(실질, 계절조정 전기대비)
│   ├── private_consumption_growth        # 민간소비증감률(실질, 계절조정 전기대비)
│   ├── facilities_investment_growth      # 설비투자증감률(실질, 계절조정 전기대비)
│   ├── construction_investment_growth    # 건설투자증감률(실질, 계절조정 전기대비)
│   ├── exports_growth                    # 재화의 수출 증감률(실질, 계절조정 전기대비)
│   ├── gdp_nominal                       # GDP(명목, 계절조정)
│   ├── gni_per_capita                    # 1인당GNI
│   ├── gross_saving_ratio                # 총저축률
│   ├── gross_investment_ratio            # 국내총투자율
│   └── trade_to_gni_ratio                # 수출입의 대 GNI 비율
├── production/
│   ├── all_industry                      # 전산업생산지수
│   ├── manufacturing/
│   │   ├── output                        # 제조업생산지수
│   │   ├── shipment                      # 제조업출하지수
│   │   ├── inventory                     # 제조업재고지수
│   │   └── utilization                   # 제조업가동률지수
│   ├── services                          # 서비스업생산지수
│   └── retail_wholesale                  # 도소매업생산지수
├── consumption/
│   ├── retail_sales                      # 소매판매액지수
│   ├── credit_card_spending              # 개인신용카드사용액
│   └── motor_vehicle_sales               # 자동차판매액지수
├── investment/
│   ├── equipment                         # 설비투자지수
│   ├── machinery_shipment                # 설비용 기계류내수출하지수
│   ├── machinery_orders                  # 국내기계수주액
│   ├── construction_completed            # 건설기성액
│   ├── building_permits                  # 건축허가면적
│   ├── construction_orders               # 건설수주액
│   └── construction_started              # 건축착공면적
├── business_cycle/
│   ├── coincident_index                  # 동행지수순환변동치
│   └── leading_index                     # 선행지수순환변동치
├── sentiment/
│   ├── business                          # 전산업 기업심리지수실적
│   ├── consumer                          # 소비자심리지수
│   ├── economic                          # 경제심리지수
│   └── manufacturing_bsi                 # 제조업업황실적BSI
├── corporate/
│   └── manufacturing/
│       ├── sales_growth                  # 제조업매출액증감률
│       ├── profit_margin                 # 제조업매출액세전순이익률
│       └── debt_ratio                    # 제조업부채비율
├── household/
│   ├── income                            # 가구당월평균소득
│   ├── apc                               # 평균소비성향
│   ├── gini                              # 지니계수
│   └── quintile_ratio                    # 5분위배율
├── employment/
│   ├── unemployment_rate                 # 실업률
│   ├── employment_rate                   # 고용률
│   ├── active_population                 # 경제활동인구
│   ├── employed_persons                  # 취업자수
│   ├── hourly_wage                       # 시간당명목임금지수
│   ├── labor_productivity                # 노동생산성지수
│   └── unit_labor_cost                   # 단위노동비용지수
├── population/
│   ├── projected                         # 추계인구
│   ├── elderly_ratio                     # 고령인구비율
│   └── fertility_rate                    # 합계출산율
├── external/
│   ├── current_account                   # 경상수지
│   ├── direct_investment_assets          # 직접투자(자산)
│   ├── direct_investment_liabilities     # 직접투자(부채)
│   ├── portfolio_investment_assets       # 증권투자(자산)
│   ├── portfolio_investment_liabilities  # 증권투자(부채)
│   ├── reserves/
│   │   ├── total                         # 외환보유액
│   │   ├── fx                            # 외환보유액(외환)
│   │   ├── gold                          # 외환보유액(금)
│   │   ├── sdr                           # 외환보유액(SDR)
│   │   └── imf                           # 외환보유액(IMF포지션)
│   ├── debt                              # 대외채무
│   └── claims                            # 대외채권
├── trade/
│   ├── exports/
│   │   ├── value                         # 수출금액지수
│   │   ├── volume                        # 수출물량지수
│   │   ├── price                         # 수출물가지수
│   │   └── semiconductor/
│   │       ├── value                     # 반도체 수출금액지수
│   │       ├── volume                    # 반도체 수출물량지수
│   │       └── price                     # 반도체 수출물가지수
│   ├── imports/
│   │   ├── value                         # 수입금액지수
│   │   ├── volume                        # 수입물량지수
│   │   ├── price                         # 수입물가지수
│   │   └── semiconductor/
│   │       ├── value                     # 반도체 수입금액지수
│   │       ├── volume                    # 반도체 수입물량지수
│   │       └── price                     # 반도체 수입물가지수
│   └── terms_of_trade/
│       ├── net                           # 순상품교역조건지수
│       └── income                        # 소득교역조건지수
├── price/
│   ├── cpi                               # 소비자물가지수
│   ├── core_cpi                          # 농산물 및 석유류제외 소비자물가지수
│   ├── living_cpi                        # 생활물가지수
│   ├── ppi                               # 생산자물가지수
│   └── producer/
│       ├── dram                          # DRAM 생산자물가
│       ├── nand                          # NAND플래시 생산자물가
│       └── logic                         # 시스템반도체 생산자물가
├── real_estate/
│   ├── house_sales_price                 # 주택매매가격지수
│   ├── house_jeonse_price                # 주택전세가격지수
│   └── land_price_change                 # 지가변동률(전기대비)
├── commodity/
│   ├── dubai_oil                         # Dubai유(현물)
│   └── gold                              # 금
└── world/
    └── rate/
        ├── policy/
        │   ├── us                        # 미국 정책금리
        │   ├── jp                        # 일본 정책금리
        │   ├── cn                        # 중국 정책금리
        │   ├── euro                      # 유로 지역 정책금리
        │   ├── uk                        # 영국 정책금리
        │   ├── kr                        # 한국 정책금리
        │   ├── ca                        # 캐나다 정책금리
        │   └── india                     # 인도 정책금리
        └── market/                       # 유로 지역은 시장금리 단일계열이 ECOS에 없어 독일(de)로 대용
            ├── us/
            │   ├── long                  # 미국 장기금리
            │   └── short                 # 미국 단기금리
            ├── jp/
            │   ├── long                  # 일본 장기금리
            │   └── short                 # 일본 단기금리
            ├── cn/
            │   ├── long                  # 중국 장기금리
            │   └── short                 # 중국 단기금리
            ├── uk/
            │   ├── long                  # 영국 장기금리
            │   └── short                 # 영국 단기금리
            ├── kr/
            │   ├── long                  # 한국 장기금리
            │   └── short                 # 한국 단기금리
            ├── ca/
            │   ├── long                  # 캐나다 장기금리
            │   └── short                 # 캐나다 단기금리
            ├── india/
            │   ├── long                  # 인도 장기금리
            │   └── short                 # 인도 단기금리
            └── de/
                ├── long                  # 독일 장기금리
                └── short                 # 독일 단기금리

전체 목록:

4. 그 밖의 모든 통계

위 목록에 없는 통계는 통계표 코드로 직접 조회합니다. ECOS가 제공하는 6가지 조회를 그대로 쓰며, 모두 dict의 목록을 돌려줍니다.

rows = ecos.fetch_series(
    "722Y001",             # 시장금리 통계표
    item_code1="0101000",  # 그 표 안의 '한국은행 기준금리' 항목
    cycle="M",             # 월별
    start="202001", end="202412",
)

값이 없는 구간은 data_value가 None으로 옵니다. 100건씩 나눠 오는 긴 시계열도 알아서 이어 붙여 한 번에 돌려줍니다.

5. 커맨드라인

설치하면 ecos 명령이 함께 깔립니다 (설치는 pip install pyecos, 명령은 ecos). 터미널에서 6가지 조회를 바로 할 수 있습니다.

ecos series 722Y001 --item 0101000 --start 202001 --end 202412  # 기준금리 시계열
ecos tables                                                     # 통계표 목록
ecos items 722Y001                                              # 한 표의 세부 항목
ecos key-statistics                                             # 100대 지표
ecos glossary DSR                                               # 용어 뜻풀이
ecos meta 경제심리지수                                          # 자료 설명

모든 명령에 --lang en(영어)·--json(JSON 출력)을 붙일 수 있고, ecos --version으로 버전을 봅니다. 더 자세히는 ecos <명령> --help.

6. AI 코딩 에이전트에서 사용

이 저장소는 Claude Code·Codex용 플러그인 마켓플레이스도 겸합니다 — series·catalog· key-statistics를 ecos 명령을 호출하는 스킬로 제공합니다. 먼저 위에서 패키지를 설치하고 API 키를 설정하세요.

6.1. Claude Code

Claude Code 채팅창에서 마켓플레이스를 추가하고 설치합니다:

/plugin marketplace add seokhoonj/pyecos
/plugin install ecos@pyecos

그런 다음 평범하게 물어보거나("기준금리 시계열 보여줘", "소비자물가 통계표 코드 찾아줘"), 스킬을 직접 호출하세요 — /ecos:series 722Y001 --item 0101000, /ecos:key-statistics.

6.2. Codex

터미널에서 마켓플레이스를 추가하고 설치합니다:

codex plugin marketplace add seokhoonj/pyecos
codex plugin add ecos@pyecos

series·catalog·key-statistics 스킬은 경제지표 요청에 반응하며, ecos <명령>으로 직접 실행해도 됩니다.

플러그인으로 설치하지 않고 쓰려면, 스킬을 스킬 디렉터리에 symlink한 뒤 접두사(ecos:) 없이 /series처럼 부르면 됩니다:

ln -s "$PWD/plugins/ecos/skills/series" ~/.claude/skills/series   # Claude Code → /series
ln -s "$PWD/plugins/ecos/skills/series" ~/.codex/skills/series    # Codex → $ecos:series

Claude Code는 바로 인식하고, Codex는 재시작해야 로딩됩니다.

7. 조회 주기

fetch_series와 series 명령이 받는 조회 주기입니다. 라이브러리에서는 코드("M"), 명령에서는 단어(monthly)를 씁니다. 각 행의 time 값이 주기에 맞춰 표기됩니다.

8. 오류

모두 ECOSError의 하위입니다. 조회 결과가 없을 뿐이면 오류가 아니라 빈 목록으로 옵니다. 많이 조회할 때는 ECOS(delay_seconds=0.6)으로 간격을 두면 제한(약 3분에 300회)을 넘지 않습니다.

9. 내장 목록에서 통계표 코드 찾기

위 목록에 없는 통계표의 코드를 찾을 때 — API 호출 없이 패키지에 내장된 통계표 목록에서 바로 검색합니다.

from pyecos import catalog

catalog.search("소비자물가")
# -> [{"stat_code": "901Y009", "stat_name": "4.2.1. 소비자물가지수", "cycle": "M", "searchable": True}, ...]

catalog.table("901Y009")   # 그 표 한 줄 (없으면 None)
catalog.tables()           # 전체 목록 (834개)

통계표 이름이 한국어라 한글 키워드나 코드로 찾습니다. 최신 목록이나 세부 항목이 필요하면 ecos.fetch_tables()·ecos.fetch_items()를 쓰세요.

10. 라이선스

MIT