지표 함수¶

모든 지표 조회 함수의 자동 생성 API 레퍼런스입니다.

금리 지표¶

get_base_rate ¶

get_base_rate(start_date: str | None = None, end_date: str | None = None, frequency: Literal['daily', 'monthly'] = 'monthly') -> pd.DataFrame

한국은행 기준금리를 조회합니다.

Parameters:

Name	Type	Description	Default
`start_date`	`str`	조회 시작일, 기본값: 1년 전. 주기에 맞춘 형식 — 'M'이면 YYYYMM, 'D'이면 YYYYMMDD.	`None`
`end_date`	`str`	조회 종료일, 기본값: 현재. (형식은 `start_date` 와 동일)	`None`
`frequency`	`str`	조회 주기 (ECOS 통계표 `722Y001` 은 일별 원천) - 'monthly': 월별 (기본값, 날짜 YYYYMM) - 'daily': 일별 (날짜 YYYYMMDD). 기준금리는 변경일에만 갱신되어 결과가 sparse 합니다 (변경이 없는 날은 행이 없음).	`'monthly'`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: 기준금리 (%) - unit: 단위

Examples:

>>> import ecos
>>> df = ecos.get_base_rate()
>>> df.head()
        date  value unit
0 2024-01-01   3.50    %

>>> df = ecos.get_base_rate(start_date="202001", end_date="202312")

>>> # 일별 (변경일 단위) 조회
>>> df = ecos.get_base_rate(
...     start_date="20200101", end_date="20231231", frequency="daily"
... )

get_treasury_yield ¶

get_treasury_yield(maturity: Literal['1Y', '3Y', '5Y', '10Y', '20Y', '30Y'] = '3Y', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

국고채 수익률을 조회합니다.

Parameters:

Name	Type	Description	Default
`maturity`	`str`	국고채 만기 - '1Y': 1년물 - '3Y': 3년물 (기본값) - '5Y': 5년물 - '10Y': 10년물 - '20Y': 20년물 - '30Y': 30년물	`'3Y'`
`start_date`	`str`	조회 시작일 (YYYYMMDD 형식), 기본값: 1년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYMMDD 형식), 기본값: 현재	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: 국고채 수익률 (%) - unit: 단위

Examples:

>>> import ecos
>>> df = ecos.get_treasury_yield()  # 3년물 기본
>>> df.head()

>>> df = ecos.get_treasury_yield(maturity="10Y")  # 10년물

get_yield_spread ¶

get_yield_spread(long_maturity: Literal['10Y', '20Y', '30Y'] = '10Y', short_maturity: Literal['1Y', '3Y', '5Y'] = '3Y', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

국고채 장단기 금리차를 계산합니다.

장단기 금리차는 경기 침체의 선행 지표로 활용됩니다. 음수 전환(역전) 시 경기 침체 가능성을 시사합니다.

Parameters:

Name	Type	Description	Default
`long_maturity`	`str`	장기 국고채 만기 ('10Y', '20Y', '30Y'), 기본값: '10Y'	`'10Y'`
`short_maturity`	`str`	단기 국고채 만기 ('1Y', '3Y', '5Y'), 기본값: '3Y'	`'3Y'`
`start_date`	`str`	조회 시작일 (YYYYMMDD 형식)	`None`
`end_date`	`str`	조회 종료일 (YYYYMMDD 형식)	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, long_yield, short_yield, spread, unit - spread: 장기금리 - 단기금리

Examples:

>>> import ecos
>>> df = ecos.get_yield_spread()  # 10년-3년 스프레드
>>> df.head()

>>> df = ecos.get_yield_spread(long_maturity="30Y", short_maturity="1Y")

get_bank_deposit_rate ¶

get_bank_deposit_rate(basis: Literal['신규취급액', '잔액'] = '신규취급액', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

예금은행 수신금리를 조회합니다.

신규취급액 기준 또는 잔액 기준 수신금리를 제공합니다.

Parameters:

Name	Type	Description	Default
`basis`	`str`	금리 산정 기준 - '신규취급액': 신규취급액 기준 (기본값) - '잔액': 잔액 기준	`'신규취급액'`
`start_date`	`str`	조회 시작일 (YYYYMM 형식), 기본값: 1년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYMM 형식), 기본값: 현재	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: 수신금리 (%) - unit: 단위

Notes

수신금리: 은행이 예금을 받을 때 지급하는 이자율
신규취급액 기준: 당월 신규로 취급된 예금의 금리
잔액 기준: 전체 예금 잔액 기준 가중평균 금리

수신금리는 기준금리의 변화를 반영하며, 예금자의 저축 수익률을 결정하는 중요한 지표입니다.

Examples:

>>> import ecos
>>> df = ecos.get_bank_deposit_rate()
>>> df.head()
        date  value unit
0 2024-01-01   3.20    %

>>> df = ecos.get_bank_deposit_rate(basis="잔액")

get_bank_lending_rate ¶

get_bank_lending_rate(basis: Literal['신규취급액', '잔액'] = '신규취급액', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

예금은행 대출금리를 조회합니다.

신규취급액 기준 또는 잔액 기준 대출금리를 제공합니다.

Parameters:

Name	Type	Description	Default
`basis`	`str`	금리 산정 기준 - '신규취급액': 신규취급액 기준 (기본값) - '잔액': 잔액 기준	`'신규취급액'`
`start_date`	`str`	조회 시작일 (YYYYMM 형식), 기본값: 1년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYMM 형식), 기본값: 현재	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: 대출금리 (%) - unit: 단위

Notes

대출금리: 은행이 대출을 실행할 때 적용하는 이자율
신규취급액 기준: 당월 신규로 실행된 대출의 금리
잔액 기준: 전체 대출 잔액 기준 가중평균 금리

대출금리는 기준금리와 시장 상황을 반영하며, 기업과 가계의 자금 조달 비용을 결정하는 핵심 지표입니다.

Examples:

>>> import ecos
>>> df = ecos.get_bank_lending_rate()
>>> df.head()
        date  value unit
0 2024-01-01   4.50    %

>>> df = ecos.get_bank_lending_rate(basis="잔액")

물가 지표¶

get_cpi ¶

get_cpi(start_date: str | None = None, end_date: str | None = None, measure: Literal['index', 'yoy', 'mom'] = 'index') -> pd.DataFrame

소비자물가지수(CPI)를 조회합니다.

한국은행 물가안정목표(2%)의 기준이 되는 물가 지표입니다.

Parameters:

Name	Type	Description	Default
`start_date`	`str`	조회 시작일 (YYYYMM 형식), 기본값: 2년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYMM 형식), 기본값: 현재	`None`
`measure`	`str`	반환 측정값 (기본값: 'index') - 'index': 원지수 (2020=100) - 'yoy': 전년동월비 (%, 인플레이션율) - 'mom': 전월비 (%)	`'index'`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: measure='index'면 지수(2020=100), 'yoy'/'mom'이면 변화율(%) - unit: 단위 ('2020=100' 또는 '%')

Notes

인플레이션율은 measure='yoy' (전년동월비)로 조회합니다.
전년동월비가 2%를 상회하면 인플레이션 압력을 의미합니다.

Examples:

>>> import ecos
>>> df = ecos.get_cpi()                 # 지수 (2020=100)
>>> df = ecos.get_cpi(measure="yoy")    # 전년동월비 (%)

get_core_cpi ¶

get_core_cpi(start_date: str | None = None, end_date: str | None = None, measure: Literal['index', 'yoy', 'mom'] = 'index') -> pd.DataFrame

근원 소비자물가지수(Core CPI)를 조회합니다.

식료품과 에너지를 제외한 물가지수로, 일시적인 물가 변동 요인을 제거한 기조적 인플레이션을 파악하는 데 활용됩니다.

Parameters:

Name	Type	Description	Default
`start_date`	`str`	조회 시작일 (YYYYMM 형식), 기본값: 2년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYMM 형식), 기본값: 현재	`None`
`measure`	`str`	반환 측정값 (기본값: 'index') - 'index': 원지수 (2020=100) - 'yoy': 전년동월비 (%, 기조적 인플레이션율) - 'mom': 전월비 (%)	`'index'`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: measure='index'면 지수(2020=100), 'yoy'/'mom'이면 변화율(%) - unit: 단위 ('2020=100' 또는 '%')

Notes

근원 CPI는 일시적 충격(유가, 농산물 가격)을 제외한 기조적 인플레이션 지표.
통화정책 결정 시 참고 지표로 중요하게 활용. 기조 인플레이션율은 measure='yoy'.

Examples:

>>> import ecos
>>> df = ecos.get_core_cpi()                # 지수
>>> df = ecos.get_core_cpi(measure="yoy")   # 전년동월비 (%)

get_cpi_monthly ¶

get_cpi_monthly(sub_category: str | None = None, start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

CPI 월별 원지수를 품목/분류별로 조회합니다.

전년동월비가 아닌 원지수(index)를 COICOP 품목 분류 전체로 제공합니다. partial-coverage 재설계 규약(#56)을 따릅니다 — sub_category 미지정 시 전체 품목을 long-format으로, 지정 시 해당 품목 단일 시계열만 반환합니다.

Parameters:

Name	Type	Description	Default
`sub_category`	`str`	세부 품목/분류(항목명 또는 item_code1). 지정 시 해당 품목 단일 시계열만 반환합니다. 미지정 시 전체 품목을 long-format으로 반환합니다. 예) '총지수', '식료품 및 비주류음료', '쌀', 또는 item_code 'A01101'. 품목명은 분류축 내에서 중복될 수 있으므로 유일 선택이 필요하면 item_code1(예: 'A01101')을 사용하세요.	`None`
`start_date`	`str`	조회 시작일 (YYYYMM 형식), 기본값: 2년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYMM 형식), 기본값: 현재	`None`

Returns:

Type	Description
`DataFrame`	`sub_category` 미지정: 컬럼 `date, category_value, value, unit` (각 품목이 행으로 포함된 long-format, `category_value`=품목명) `sub_category` 지정: 컬럼 `date, value, unit` (단일 시계열)

Raises:

Type	Description
`ValueError`	지정한 `sub_category` 가 존재하지 않는 경우 (사용 가능 항목을 함께 안내).

Notes

원지수는 기준년도(2020=100)를 100으로 한 지수값
총지수 단일 시계열은 get_cpi() 함수 사용 (동일하게 지수 레벨 반환)
CPI 통계표(901Y009)는 계층형입니다 — long-format에는 총지수(item_code '0'), COICOP 대분류(A=식료품 등), 중·소분류, 개별 품목(쌀 등)이 모두 포함됩니다. 특정 시계열이 필요하면 sub_category 로 선택하세요(축 간 단순 합산 금지).
특수분류(상품/서비스/근원 등) 선택은 get_cpi_by_category 를 사용하세요.
ecos.get_indicator("cpi_monthly") 레지스트리 경로는 총지수 단일 시계열만 반환합니다(저수준 접근). 이 함수는 전체 품목 분류를 제공합니다.

Examples:

>>> import ecos
>>> # 전체 품목 long-format
>>> df = ecos.get_cpi_monthly()
>>> df.head()
        date category_value   value unit

>>> # 총지수만
>>> df = ecos.get_cpi_monthly(sub_category="총지수")

>>> # 쌀 가격지수 (item_code도 허용)
>>> df = ecos.get_cpi_monthly(sub_category="쌀")

get_cpi_by_category ¶

get_cpi_by_category(category: Literal['전체', '상품', '서비스', '식품_에너지제외', '농산물_석유제외', '식료품_비주류음료', '주거_수도_전기', '교통'] = '전체', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

CPI 세부 항목별 지수를 조회합니다.

상품, 서비스, 식품 등 세부 항목별 물가지수를 제공합니다.

Parameters:

Name	Type	Description	Default
`category`	`str`	CPI 세부 항목 - '전체': 소비자물가지수 (기본값) - '상품': 상품 물가지수 - '서비스': 서비스 물가지수 - '식품_에너지제외': 식품 및 에너지 제외 지수 - '농산물_석유제외': 농산물 및 석유류 제외 지수 - '식료품_비주류음료': 식료품 및 비주류음료 - '주거_수도_전기': 주거, 수도, 전기 및 연료 - '교통': 교통	`'전체'`
`start_date`	`str`	조회 시작일 (YYYYMM 형식), 기본값: 2년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYMM 형식), 기본값: 현재	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: CPI 카테고리별 지수 - unit: 단위

Notes

각 카테고리별로 물가 변동을 세부적으로 파악 가능
'식품_에너지제외'는 근원 물가와 유사한 개념
상품과 서비스 물가의 괴리는 수요 구조 변화를 반영
특수분류(전체/상품/서비스/제외 시리즈)는 stat_code 901Y010, COICOP 1단계(식료품/주거/교통 등)는 stat_code 901Y009를 사용

Examples:

>>> import ecos
>>> df = ecos.get_cpi_by_category(category="식품_에너지제외")
>>> df.head()
        date   value  unit
0 2023-01-01  103.50  지수

>>> df = ecos.get_cpi_by_category(category="교통")
>>> df.head()

get_ppi ¶

get_ppi(start_date: str | None = None, end_date: str | None = None, measure: Literal['index', 'yoy', 'mom'] = 'index') -> pd.DataFrame

생산자물가지수(PPI)를 조회합니다.

생산자물가는 소비자물가의 선행 지표로 활용됩니다.

Parameters:

Name	Type	Description	Default
`start_date`	`str`	조회 시작일 (YYYYMM 형식), 기본값: 2년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYMM 형식), 기본값: 현재	`None`
`measure`	`str`	반환 측정값 (기본값: 'index') - 'index': 원지수 (2020=100) - 'yoy': 전년동월비 (%) - 'mom': 전월비 (%)	`'index'`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: measure='index'면 지수(2020=100), 'yoy'/'mom'이면 변화율(%) - unit: 단위 ('2020=100' 또는 '%')

Notes

PPI 상승 → CPI 상승으로 이어지는 경향. 변화율은 measure='yoy'/'mom'.
기업의 원가 부담을 나타내는 지표

Examples:

>>> import ecos
>>> df = ecos.get_ppi()                 # 지수
>>> df = ecos.get_ppi(measure="yoy")    # 전년동월비 (%)

성장 지표¶

get_gdp ¶

get_gdp(frequency: Literal['quarterly', 'annual'] = 'quarterly', basis: Literal['real', 'nominal'] = 'real', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

국내총생산(GDP)을 조회합니다.

Parameters:

Name	Type	Description	Default
`frequency`	`str`	조회 주기 - 'quarterly': 분기 (기본값) - 'annual': 연간	`'quarterly'`
`basis`	`str`	GDP 기준 - 'real': 실질 GDP (기본값) - 'nominal': 명목 GDP	`'real'`
`start_date`	`str`	조회 시작일 - 분기: YYYYQN 형식 (예: 2020Q1) - 연간: YYYY 형식 (예: 2020)	`None`
`end_date`	`str`	조회 종료일	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: GDP (십억원) - unit: 단위

Notes

실질 GDP: 물가 변동을 제외한 실제 생산량 변화
명목 GDP: 당해 연도 가격 기준 GDP

Examples:

>>> import ecos
>>> df = ecos.get_gdp()  # 분기별 실질 GDP
>>> df.head()

>>> df = ecos.get_gdp(frequency="annual", basis="nominal")  # 연간 명목 GDP

get_gdp_deflator ¶

get_gdp_deflator(frequency: Literal['quarterly', 'annual'] = 'quarterly', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

GDP 디플레이터를 조회합니다.

GDP 디플레이터는 명목 GDP와 실질 GDP의 비율로 계산되는 종합 물가지수입니다.

Parameters:

Name	Type	Description	Default
`frequency`	`str`	조회 주기 - 'quarterly': 분기 (기본값) - 'annual': 연간	`'quarterly'`
`start_date`	`str`	조회 시작일	`None`
`end_date`	`str`	조회 종료일	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: GDP 디플레이터 - unit: 단위

Notes

GDP 디플레이터 = (명목 GDP / 실질 GDP) × 100
CPI보다 포괄적인 물가 지표
국내에서 생산된 모든 재화와 서비스의 가격 변화 반영

Examples:

>>> import ecos
>>> df = ecos.get_gdp_deflator()
>>> df.head()

get_gdp_growth_rate ¶

get_gdp_growth_rate(frequency: Literal['quarterly', 'annual'] = 'quarterly', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

실질 GDP 성장률(%)을 조회합니다.

ECOS 통계표 902Y015(국제 주요국 경제성장률, OECD 출처)의 한국 계열을 사용합니다. 분기는 전기대비(QoQ, 계절조정), 연간은 전년대비(YoY) 성장률입니다.

Parameters:

Name	Type	Description	Default
`frequency`	`str`	조회 주기 - 'quarterly': 분기 (기본값) - 'annual': 연간	`'quarterly'`
`start_date`	`str`	조회 시작일 - 분기: YYYYQN 형식 (예: 2020Q1) - 연간: YYYY 형식 (예: 2020)	`None`
`end_date`	`str`	조회 종료일	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: GDP 성장률 (%) - unit: 단위

Notes

분기(quarterly): 전기대비(QoQ) 계절조정 성장률
연간(annual): 전년대비(YoY) 성장률
출처가 OECD이므로 한국은행 국민계정 속보치와 소수점 단위 차이가 있을 수 있습니다.

GDP 성장률은 경제 성장의 속도를 나타내는 가장 핵심적인 지표입니다.

Examples:

>>> import ecos
>>> df = ecos.get_gdp_growth_rate()
>>> df.head()
        date  value unit
0 2024-01-01   2.3    %

get_gdp_by_industry ¶

get_gdp_by_industry(basis: Literal['real', 'nominal'] = 'real', seasonal_adj: bool = True, frequency: Literal['quarterly', 'annual'] = 'quarterly', sub_category: str | None = None, start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

경제활동별(산업별) GDP를 조회합니다.

농림어업, 광공업, 서비스업 등 경제활동별 부가가치 전체 시리즈를 제공합니다. partial-coverage 재설계 규약(#56)을 따릅니다 — sub_category 미지정 시 전체 산업을 long-format으로, 지정 시 해당 산업 단일 시계열만 반환합니다.

Parameters:

Name	Type	Description	Default
`basis`	`str`	GDP 기준 - 'real': 실질 GDP (기본값) - 'nominal': 명목 GDP	`'real'`
`seasonal_adj`	`bool`	계절조정 여부 (기본값: True)	`True`
`frequency`	`str`	조회 주기 - 'quarterly': 분기 (기본값) - 'annual': 연간	`'quarterly'`
`sub_category`	`str`	세부 산업(항목명 또는 item_code1). 지정 시 해당 산업 단일 시계열만 반환합니다. 미지정 시 전체 산업을 long-format으로 반환합니다.	`None`
`start_date`	`str`	조회 시작일	`None`
`end_date`	`str`	조회 종료일	`None`

Returns:

Type	Description
`DataFrame`	`sub_category` 미지정: 컬럼 `date, category_value, value, unit` (각 산업이 행으로 포함된 long-format, `category_value`=산업명) `sub_category` 지정: 컬럼 `date, value, unit` (단일 시계열)

Raises:

Type	Description
`ValueError`	지원하지 않는 basis/seasonal_adj/frequency 조합이거나, 지정한 `sub_category` 가 존재하지 않는 경우 (사용 가능 항목을 함께 안내).

Notes

계절조정: 계절적 요인 제거
원계열: 계절조정하지 않은 원자료
이 통계표는 계층형입니다 — long-format에는 총계·소계(예: '총부가가치')와 세부 산업이 함께 포함되므로, category_value 를 단순 합산하면 중복 집계됩니다. 특정 시계열이 필요하면 sub_category 로 선택하세요.

산업별 GDP는 경제 구조와 각 산업의 기여도를 파악하는 데 활용됩니다.

Examples:

>>> import ecos
>>> # 전체 산업 long-format
>>> df = ecos.get_gdp_by_industry()
>>> df.head()
        date category_value     value   unit

>>> # 제조업 단일 시계열
>>> df = ecos.get_gdp_by_industry(sub_category="제조업")

>>> df = ecos.get_gdp_by_industry(basis="nominal", seasonal_adj=False)

get_gdp_by_expenditure ¶

get_gdp_by_expenditure(basis: Literal['real', 'nominal'] = 'real', frequency: Literal['quarterly', 'annual'] = 'quarterly', sub_category: str | None = None, start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

지출항목별 GDP를 조회합니다.

민간소비, 정부소비, 투자, 수출입 등 지출항목별 GDP 전체 시리즈를 제공합니다. partial-coverage 재설계 규약(#56)을 따릅니다 — sub_category 미지정 시 전체 지출항목을 long-format으로, 지정 시 해당 항목 단일 시계열만 반환합니다.

Parameters:

Name	Type	Description	Default
`basis`	`str`	GDP 기준 - 'real': 실질 GDP (기본값) - 'nominal': 명목 GDP	`'real'`
`frequency`	`str`	조회 주기 - 'quarterly': 분기 (기본값) - 'annual': 연간	`'quarterly'`
`sub_category`	`str`	세부 지출항목(항목명 또는 item_code1). 지정 시 해당 항목 단일 시계열만 반환합니다. 미지정 시 전체 지출항목을 long-format으로 반환합니다.	`None`
`start_date`	`str`	조회 시작일	`None`
`end_date`	`str`	조회 종료일	`None`

Returns:

Type	Description
`DataFrame`	`sub_category` 미지정: 컬럼 `date, category_value, value, unit` (각 지출항목이 행으로 포함된 long-format, `category_value`=항목명) `sub_category` 지정: 컬럼 `date, value, unit` (단일 시계열)

Raises:

Type	Description
`ValueError`	지원하지 않는 basis 조합이거나, 지정한 `sub_category` 가 존재하지 않는 경우 (사용 가능 항목을 함께 안내).

Notes

GDP 지출항목: - 민간소비: 가계의 소비지출 - 정부소비: 정부의 소비지출 - 총고정자본형성: 기업 및 정부의 투자 - 수출 - 수입: 순수출

이 통계표는 계층형입니다 — long-format에는 총계('국내총생산에 대한 지출')와 소계('총고정자본형성', '최종소비지출' 등) 및 그 구성요소('민간', '정부' 등)가 함께 포함되므로 category_value 를 단순 합산하면 중복 집계됩니다. 특정 시계열이 필요하면 sub_category 로 선택하세요.

지출항목별 GDP는 경제 성장의 원천을 파악하는 데 활용됩니다.

Examples:

>>> import ecos
>>> # 전체 지출항목 long-format
>>> df = ecos.get_gdp_by_expenditure()
>>> df.head()

>>> # 민간소비 단일 시계열
>>> df = ecos.get_gdp_by_expenditure(sub_category="민간소비지출")

>>> df = ecos.get_gdp_by_expenditure(basis="nominal")

get_gdp_deflator_by_industry ¶

get_gdp_deflator_by_industry(frequency: Literal['quarterly', 'annual'] = 'quarterly', sub_category: str | None = None, start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

경제활동별(산업별) GDP 디플레이터를 조회합니다.

산업별 물가 변화를 나타내는 GDP 디플레이터 전체 시리즈를 제공합니다. partial-coverage 재설계 규약(#56)을 따릅니다 — sub_category 미지정 시 전체 산업을 long-format으로, 지정 시 해당 산업 단일 시계열만 반환합니다.

Parameters:

Name	Type	Description	Default
`frequency`	`str`	조회 주기 - 'quarterly': 분기 (기본값) - 'annual': 연간	`'quarterly'`
`sub_category`	`str`	세부 산업(항목명 또는 item_code1). 지정 시 해당 산업 단일 시계열만 반환합니다. 미지정 시 전체 산업을 long-format으로 반환합니다.	`None`
`start_date`	`str`	조회 시작일	`None`
`end_date`	`str`	조회 종료일	`None`

Returns:

Type	Description
`DataFrame`	`sub_category` 미지정: 컬럼 `date, category_value, value, unit` (각 산업이 행으로 포함된 long-format, `category_value`=산업명) `sub_category` 지정: 컬럼 `date, value, unit` (단일 시계열)

Raises:

Type	Description
`ValueError`	지정한 `sub_category` 가 존재하지 않는 경우 (사용 가능 항목을 함께 안내).

Notes

GDP 디플레이터 = (명목 GDP / 실질 GDP) × 100
각 산업별로 물가 변화를 측정
이 통계표는 계층형입니다 — long-format에는 총계('국내총생산(시장가격)', '총부가가치(기초가격)')와 세부 산업이 함께 포함되므로, 특정 시계열이 필요하면 sub_category 로 선택하세요.

산업별 GDP 디플레이터는 산업별 물가 동향을 파악하는 데 활용됩니다.

Examples:

>>> import ecos
>>> # 전체 산업 long-format
>>> df = ecos.get_gdp_deflator_by_industry()
>>> df.head()

>>> # 제조업 단일 시계열
>>> df = ecos.get_gdp_deflator_by_industry(sub_category="제조업")

>>> df = ecos.get_gdp_deflator_by_industry(frequency="annual")

통화 지표¶

get_money_supply ¶

get_money_supply(indicator: Literal['M1', 'M2', 'Lf'] = 'M2', start_date: str | None = None, end_date: str | None = None, frequency: Literal['monthly', 'quarterly', 'annual'] = 'monthly') -> pd.DataFrame

통화량을 조회합니다.

Parameters:

Name	Type	Description	Default
`indicator`	`str`	통화 지표 - 'M1': 협의통화 (현금 + 요구불예금) - 'M2': 광의통화 (기본값, 가장 많이 사용) - 'Lf': 금융기관유동성	`'M2'`
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식 (월 `YYYYMM` / 분기 `YYYYQn` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`frequency`	`str`	조회 주기. `'monthly'`(기본)/`'quarterly'`/`'annual'`.	`'monthly'`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: 통화량 (십억원) - unit: 단위

Raises:

Type	Description
`ValueError`	지원하지 않는 `indicator`/`frequency` 일 때.

Notes

M1 (협의통화): 즉시 사용 가능한 화폐
M2 (광의통화): M1 + 저축성 예금, 시장형 금융상품 등
Lf (금융기관유동성): M2 + 생명보험 계약 준비금 등

통화량 증가율은 인플레이션 및 자산 가격에 영향을 미칩니다.

Examples:

>>> import ecos
>>> df = ecos.get_money_supply()  # M2 기본(월)
>>> df.head()

>>> df = ecos.get_money_supply(indicator="M1")
>>> df = ecos.get_money_supply(frequency="annual")

get_m1_variants ¶

get_m1_variants(variant: Literal['평잔_계절조정', '평잔_원계열', '말잔_계절조정'] = '말잔_계절조정', start_date: str | None = None, end_date: str | None = None, frequency: Literal['monthly', 'quarterly', 'annual'] = 'monthly') -> pd.DataFrame

M1 세부 데이터를 조회합니다.

평잔/말잔, 계절조정/원계열 등 M1 통화량의 다양한 변형을 제공합니다.

Parameters:

Name	Type	Description	Default
`variant`	`str`	M1 변형 종류 - '평잔_계절조정': 평잔 계절조정 계열 - '평잔_원계열': 평잔 원계열 - '말잔_계절조정': 말잔 계절조정 계열 (기본값)	`'말잔_계절조정'`
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식 (월 `YYYYMM` / 분기 `YYYYQn` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`frequency`	`str`	조회 주기. `'monthly'`(기본)/`'quarterly'`/`'annual'`.	`'monthly'`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: M1 (십억원) - unit: 단위

Raises:

Type	Description
`ValueError`	지원하지 않는 `variant`/`frequency` 일 때.

Notes

평잔: 기간 중 평균 잔액
말잔: 기말 잔액
계절조정: 계절적 요인 제거

Examples:

>>> import ecos
>>> df = ecos.get_m1_variants()
>>> df.head()

>>> df = ecos.get_m1_variants(variant="평잔_원계열")
>>> df = ecos.get_m1_variants(frequency="annual")

get_m2_variants ¶

get_m2_variants(variant: Literal['평잔_계절조정', '평잔_원계열', '말잔_계절조정'] = '말잔_계절조정', start_date: str | None = None, end_date: str | None = None, frequency: Literal['monthly', 'quarterly', 'annual'] = 'monthly') -> pd.DataFrame

M2 세부 데이터를 조회합니다.

평잔/말잔, 계절조정/원계열 등 M2 통화량의 다양한 변형을 제공합니다.

Parameters:

Name	Type	Description	Default
`variant`	`str`	M2 변형 종류 - '평잔_계절조정': 평잔 계절조정 계열 - '평잔_원계열': 평잔 원계열 - '말잔_계절조정': 말잔 계절조정 계열 (기본값)	`'말잔_계절조정'`
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식 (월 `YYYYMM` / 분기 `YYYYQn` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`frequency`	`str`	조회 주기. `'monthly'`(기본)/`'quarterly'`/`'annual'`.	`'monthly'`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: M2 (십억원) - unit: 단위

Raises:

Type	Description
`ValueError`	지원하지 않는 `variant`/`frequency` 일 때.

Notes

평잔: 기간 중 평균 잔액
말잔: 기말 잔액
계절조정: 계절적 요인 제거

M2 변형 데이터는 통화량 추세 분석에 유용합니다.

Examples:

>>> import ecos
>>> df = ecos.get_m2_variants()
>>> df.head()

>>> df = ecos.get_m2_variants(variant="평잔_원계열")
>>> df = ecos.get_m2_variants(frequency="annual")

get_m2_by_holder ¶

get_m2_by_holder(variant: Literal['평잔_계절조정', '평잔_원계열', '말잔_계절조정', '말잔_원계열'] = '말잔_원계열', sub_category: str | None = None, start_date: str | None = None, end_date: str | None = None, frequency: Literal['monthly', 'quarterly', 'annual'] = 'monthly') -> pd.DataFrame

M2 경제주체별 보유 현황을 조회합니다.

가계 및 비영리단체, 비금융기업, 보험기관, 연금기금 등 경제주체별 M2 보유액을 제공합니다. partial-coverage 재설계 규약(#56)을 따릅니다 — sub_category 미지정 시 전체 경제주체를 long-format으로, 지정 시 해당 주체 단일 시계열만 반환합니다.

Parameters:

Name	Type	Description	Default
`variant`	`str`	M2 변형 종류 - '평잔_계절조정': 평잔 계절조정 계열 - '평잔_원계열': 평잔 원계열 - '말잔_계절조정': 말잔 계절조정 계열 - '말잔_원계열': 말잔 원계열 (기본값)	`'말잔_원계열'`
`sub_category`	`str`	경제주체(항목명 또는 item_code1). 지정 시 해당 주체 단일 시계열만, 미지정 시 전체 주체를 long-format으로 반환합니다. 예) '가계 및 비영리단체', '비금융기업', 또는 item_code 'BBGAJ1'.	`None`
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식 (월 `YYYYMM` / 분기 `YYYYQn` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`frequency`	`str`	조회 주기. `'monthly'`(기본)/`'quarterly'`/`'annual'`.	`'monthly'`

Returns:

Type	Description
`DataFrame`	`sub_category` 미지정: 컬럼 `date, category_value, value, unit` (각 경제주체가 행으로 포함된 long-format, `category_value`=주체명). 이 통계표에는 총계(M2 전체)와 주체별 항목이 함께 포함되므로 주체 간 단순 합산은 금지합니다. `sub_category` 지정: 컬럼 `date, value, unit` (단일 시계열). value 단위: 십억원

Raises:

Type	Description
`ValueError`	지원하지 않는 `variant`/`frequency` 이거나 `sub_category` 가 없을 때.

Notes

경제주체별 M2 보유 현황은 자금 흐름과 유동성 분포를 파악하는 데 중요한 지표입니다.

Examples:

>>> import ecos
>>> df = ecos.get_m2_by_holder()  # 전체 주체 long-format
>>> df = ecos.get_m2_by_holder(sub_category="가계 및 비영리단체")  # 단일 주체
>>> df = ecos.get_m2_by_holder(variant="평잔_계절조정")
>>> df = ecos.get_m2_by_holder(frequency="annual")

get_bank_lending ¶

get_bank_lending(sector: Literal['household', 'all'] = 'all', start_date: str | None = None, end_date: str | None = None, frequency: Literal['monthly', 'quarterly', 'annual'] = 'monthly') -> pd.DataFrame

은행 대출금을 조회합니다.

Parameters:

Name	Type	Description	Default
`sector`	`str`	대출 부문 - 'all': 예금은행 전체 대출금 (기본값) - 'household': 예금취급기관 가계대출	`'all'`
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식 (월 `YYYYMM` / 분기 `YYYYQn` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`frequency`	`str`	조회 주기. `'monthly'`(기본)/`'quarterly'`/`'annual'`.	`'monthly'`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: 대출금 (십억원) - unit: 단위

Raises:

Type	Description
`ValueError`	지원하지 않는 `sector`/`frequency` 일 때.

Notes

가계대출 증가: 소비 증가 및 부동산 가격 상승 요인
기업대출은 별도 통계표 (산업별대출금 등) 사용 필요

Examples:

>>> import ecos
>>> df = ecos.get_bank_lending()
>>> df.head()

>>> df = ecos.get_bank_lending(sector="household")  # 가계대출
>>> df = ecos.get_bank_lending(frequency="annual")

get_household_credit ¶

get_household_credit(category: Literal['업권별', '용도별'] = '업권별', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

가계신용(분기)을 조회합니다.

업권별 또는 용도별 가계신용 잔액을 제공합니다.

Parameters:

Name	Type	Description	Default
`category`	`str`	가계신용 분류 - '업권별': 은행, 비은행 등 업권별 (기본값) - '용도별': 주택담보대출, 기타대출 등 용도별	`'업권별'`
`start_date`	`str`	조회 시작일 (YYYYQN 형식, 예: 2024Q1), 기본값: 5년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYQN 형식), 기본값: 현재 분기	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: 가계신용 (십억원) - unit: 단위

Notes

가계신용 = 가계대출 + 판매신용

가계신용 증가율은 가계부채 건전성과 소비 여력을 판단하는 중요한 지표입니다.

Examples:

>>> import ecos
>>> df = ecos.get_household_credit()
>>> df.head()

>>> df = ecos.get_household_credit(category="용도별")

get_household_lending_detail ¶

get_household_lending_detail(sub_category: str | None = None, start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

예금취급기관 가계대출(용도별)을 조회합니다.

주택관련대출/기타대출을 기관(예금취급기관/예금은행/비은행)별로 제공합니다. partial-coverage 재설계 규약(#56)을 따릅니다 — sub_category 미지정 시 전체 분류를 long-format으로, 지정 시 해당 분류 단일 시계열만 반환합니다.

Parameters:

Name	Type	Description	Default
`sub_category`	`str`	세부 분류(항목명 또는 item_code1). 지정 시 해당 분류 단일 시계열만 반환합니다. 미지정 시 전체 분류를 long-format으로 반환합니다. 예) '주택관련대출-예금취급기관', '기타대출-예금은행', 또는 item_code '11100A0'. 항목명은 길고 중복 가능하므로 유일 선택은 item_code를 권장합니다.	`None`
`start_date`	`str`	조회 시작일 (YYYYMM 형식), 기본값: 3년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYMM 형식), 기본값: 현재	`None`

Returns:

Type	Description
`DataFrame`	`sub_category` 미지정: 컬럼 `date, category_value, value, unit` (각 분류가 행으로 포함된 long-format, `category_value`=분류명) `sub_category` 지정: 컬럼 `date, value, unit` (단일 시계열)

Raises:

Type	Description
`ValueError`	지정한 `sub_category` 가 존재하지 않는 경우 (사용 가능 항목을 함께 안내).

Notes

예금취급기관 = 은행 + 비은행 예금취급기관

이 통계표(151Y005)는 총계('예금취급기관')와 용도×기관 분류, [참고] 항목이 함께 있는 단일 분류축(item_code1)입니다. long-format에는 총계도 포함되므로 특정 시계열이 필요하면 sub_category 로 선택하세요(단순 합산 금지).

용도별 가계대출 현황은 부동산 시장과 가계 소비 패턴을 분석하는 데 활용됩니다.

Examples:

>>> import ecos
>>> # 전체 분류 long-format
>>> df = ecos.get_household_lending_detail()
>>> df.head()
        date category_value   value unit

>>> # 주택관련대출(예금취급기관) 단일 시계열
>>> df = ecos.get_household_lending_detail(sub_category="11100A0")

>>> df = ecos.get_household_lending_detail(start_date="202201", end_date="202412")

get_borrower_loan ¶

get_borrower_loan(loan_type: Literal['신규', '잔액'] = '잔액', category: Literal['전체', '성별', '연령별', '지역별', '업권별', '담보유형별', '다중대출별'] = '전체', sub_category: str | None = None, start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

차주별 가계대출을 조회합니다.

가계대출 신규취급액(181Y001) 또는 잔액(181Y002)을 분류축별로 제공합니다.

실제 ECOS 구조는 stat_code가 신규/잔액 2개뿐이고 모든 분류축(연령·지역·업권· 담보유형·다중대출)은 item_code1 prefix로 표현됩니다. 이 함수는 category로 분류축을 선택하면 해당 축의 모든 세부 항목을 조회한 뒤,

sub_category 미지정 시: long-format(축 전체)으로 반환하며 category_value 컬럼에 세부 항목명을 담습니다.
sub_category 지정 시: 해당 세부 항목 단일 시계열만 반환합니다.

Parameters:

Name	Type	Description	Default
`loan_type`	`str`	대출 유형 - '신규': 신규취급액 - '잔액': 잔액 (기본값)	`'잔액'`
`category`	`str`	분류축 - '전체': 차주 전체 (기본값, item_code `0000`) - '성별': 성별 (남성/여성, prefix B) - '연령별': 연령대별 (prefix C) - '지역별': 지역별 (prefix D) - '업권별': 업권별 (은행/비은행, prefix E) - '담보유형별': 담보 유형별 (주담대/신용/전세 등, prefix F) - '다중대출별': 다중대출 건수별 (prefix G)	`'전체'`
`sub_category`	`str`	세부 항목. 지정 시 해당 항목 단일 시계열만 반환합니다. 세부 항목명(`category_value`) 또는 item_code 둘 다 허용합니다. 미지정 시 분류축 전체를 long-format으로 반환합니다.	`None`
`start_date`	`str`	조회 시작일 (YYYYQN 형식, 예: 2024Q1), 기본값: 5년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYQN 형식), 기본값: 현재 분기	`None`

Returns:

Type	Description
`DataFrame`	`sub_category` 미지정: 컬럼 `date, category_value, value, unit` (분류축의 각 세부 항목이 행으로 포함된 long-format) `sub_category` 지정: 컬럼 `date, value, unit` (단일 시계열)

Raises:

Type	Description
`ValueError`	loan_type/category가 허용 값이 아니거나, 지정한 sub_category가 해당 분류축에 존재하지 않는 경우 (사용 가능한 항목을 함께 안내).

Notes

차주별 가계대출 통계는 가계부채의 질적 구조를 파악하는 데 중요한 지표입니다.

청년층/고령층 대출 비중 (연령별)
수도권/지방 대출 비중 (지역별)
은행/비은행 대출 비중 (업권별)

Examples:

>>> import ecos
>>> # 연령별 잔액 전체 (long-format)
>>> df = ecos.get_borrower_loan(loan_type="잔액", category="연령별")
>>> df.head()
        date category_value      value unit

>>> # 연령별 중 30대 단일 시계열
>>> df = ecos.get_borrower_loan(
...     loan_type="잔액", category="연령별", sub_category="30대"
... )

채권 지표¶

get_bond_market ¶

get_bond_market(bond_type: Literal['종류별', '시장별'] = '종류별', measure: Literal['거래대금', '거래량', '상장잔액', '상장종목수'] = '거래대금', sub_category: str | None = None, start_date: str | None = None, end_date: str | None = None, frequency: Literal['monthly', 'annual'] = 'monthly') -> pd.DataFrame

채권시장 거래통계를 종류별 또는 시장별로 조회합니다.

국채/회사채 등 채권 종류별, 또는 국채전문/일반채권 등 시장별 거래대금·거래량· 상장잔액·상장종목수를 제공합니다. partial-coverage 재설계 규약(#56)을 따릅니다 — sub_category 미지정 시 전체 분류를 long-format으로, 지정 시 해당 분류 단일 시계열만 반환합니다.

.. note:: 이 함수는 채권 수익률(%)이 아니라 채권시장 거래통계를 반환합니다. 채권/국고채 수익률(연%)은 :func:get_treasury_yield 를 사용하세요.

Parameters:

Name	Type	Description	Default
`bond_type`	`str`	채권 분류 기준 - '종류별': 합계/국채/지방채/특수채/회사채/외국채 (기본값, 901Y015) - '시장별': 합계/국채전문/일반채권/소액채권/신고매매 (901Y120)	`'종류별'`
`measure`	`str`	측정 지표 (한 차원을 이 값으로 고정한 뒤 분류축을 분류합니다) - '거래대금' (기본값), '거래량' - '상장잔액', '상장종목수' (`bond_type='종류별'` 에서만 지원)	`'거래대금'`
`sub_category`	`str`	세부 분류(분류명 또는 item_code). 지정 시 해당 분류 단일 시계열만 반환합니다. 미지정 시 전체 분류를 long-format으로 반환합니다. 예) 종류별: '국채' 또는 '4' / 시장별: '국채전문 유통시장' 또는 '0202'	`None`
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식 (월 `YYYYMM` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`frequency`	`str`	조회 주기. `'monthly'`(기본)/`'annual'`. 두 통계표(`901Y015`/`901Y120`)는 월·연 자료만 제공합니다.	`'monthly'`

Returns:

Type	Description
`DataFrame`	`sub_category` 미지정: 컬럼 `date, category_value, value, unit` (각 분류가 행으로 포함된 long-format, `category_value`=분류명) `sub_category` 지정: 컬럼 `date, value, unit` (단일 시계열)

Raises:

Type	Description
`ValueError`	bond_type/measure/frequency가 허용 값이 아니거나, 지정한 `sub_category` 가 존재하지 않는 경우 (사용 가능 항목을 함께 안내).

Notes

국채: 정부가 발행하는 채권, 가장 안전한 자산
회사채: 기업이 발행하는 채권, 신용등급에 따라 수익률 차이
두 통계표 모두 분류축에 '합계' 행이 포함되므로 long-format을 단순 합산하면 중복 집계됩니다. 특정 시계열은 sub_category 로 선택하세요.

채권 거래 동향은 금리 정책·경기 전망·인플레이션 기대를 반영합니다.

Examples:

>>> import ecos
>>> # 종류별 거래대금 전체 (long-format)
>>> df = ecos.get_bond_market()
>>> df.head()
        date category_value  value unit

>>> # 국채만
>>> df = ecos.get_bond_market(sub_category="국채")

>>> # 시장별 거래량
>>> df = ecos.get_bond_market(bond_type="시장별", measure="거래량")

>>> # 연간 종류별 거래대금
>>> df = ecos.get_bond_market(frequency="annual")

재정 지표¶

get_fiscal_balance ¶

get_fiscal_balance(start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

통합재정수지를 조회합니다.

통합재정수지는 중앙정부와 지방정부를 합한 일반정부의 재정수지로, 정부의 재정건전성을 나타내는 핵심 지표입니다.

Parameters:

Name	Type	Description	Default
`start_date`	`str`	조회 시작일 (YYYYMM 형식), 기본값: 2년 전	`None`
`end_date`	`str`	조회 종료일 (YYYYMM 형식), 기본값: 현재	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: 통합재정수지 (십억원) - unit: 단위

Notes

통합재정수지 = 총수입 - 총지출
흑자(+): 재정 여력 있음
적자(-): 재정 건전성 악화

통합재정수지는 국가채무 증감과 직접적인 관련이 있으며, 지속적인 적자는 국가 신용등급에 영향을 미칠 수 있습니다.

Examples:

>>> import ecos
>>> df = ecos.get_fiscal_balance()
>>> df.head()
        date    value  unit
0 2023-01-01  -5200.0  십억원
1 2023-02-01  -3800.0  십억원

>>> df = ecos.get_fiscal_balance(start_date="202301", end_date="202312")

주식시장 지표¶

get_stock_index ¶

get_stock_index(frequency: Literal['daily', 'monthly'] = 'daily', sub_category: str | None = None, start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

주가지수를 조회합니다.

KOSPI 종합주가지수를 일별 또는 월별로 조회합니다. sub_category 를 지정하면 같은 주식시장 통계표의 다른 항목(시가총액·거래량·KOSDAQ 지수 등)을 선택할 수 있습니다.

Parameters:

Name	Type	Description	Default
`frequency`	`str`	조회 주기 - 'daily': 일별 (기본값) — KOSPI 지수 - 'monthly': 월별 — KOSPI 종가(지수)	`'daily'`
`sub_category`	`str`	주식시장 통계표의 다른 항목(항목명 또는 item_code1)을 선택합니다. 미지정 시 KOSPI 지수를 반환합니다. 예) 월별: 'KOSPI_시가총액', 'KOSPI_거래대금', 'KOSDAQ_종가'	`None`
`start_date`	`str`	조회 시작일 - daily: YYYYMMDD 형식 (예: 20240101) - monthly: YYYYMM 형식 (예: 202401) 기본값: 1년 전(일별) 또는 2년 전(월별)	`None`
`end_date`	`str`	조회 종료일 (형식은 start_date와 동일)	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit - date: 날짜 (datetime) - value: 주가지수(기본) 또는 선택한 항목 값 - unit: 단위 (포인트 등)

Raises:

Type	Description
`ValueError`	지정한 `sub_category` 가 존재하지 않는 경우 (사용 가능 항목을 함께 안내).

Notes

KOSPI(Korea Composite Stock Price Index)는 한국거래소 유가증권시장의 대표 지수
1980년 1월 4일 기준시점 100포인트
시가총액 가중 방식으로 계산
v0.3.0(#60): 월별 기본값이 1010000(KOSPI 회사수, 오류)에서 1070000(KOSPI 종가, 지수)로 정정되었습니다.

주가지수는 경기 선행지표로 활용되며, 투자심리와 경제 전망을 반영합니다.

Examples:

>>> import ecos
>>> df = ecos.get_stock_index()  # 일별 KOSPI 지수
>>> df.head()
        date    value     unit
0 2024-01-02  2655.28  포인트

>>> df = ecos.get_stock_index(frequency="monthly")  # 월별 KOSPI 종가(지수)

>>> # 월별 KOSPI 시가총액
>>> df = ecos.get_stock_index(frequency="monthly", sub_category="KOSPI_시가총액")

get_investor_trading ¶

get_investor_trading(action: Literal['순매수', '매수', '매도'] = '순매수', metric: Literal['거래대금', '거래량'] = '거래대금', sub_category: str | None = None, start_date: str | None = None, end_date: str | None = None, frequency: Literal['monthly', 'annual'] = 'monthly') -> pd.DataFrame

투자자별 주식거래를 조회합니다.

기관·개인·외국인 등 투자자별 매도/매수/순매수를 거래대금 또는 거래량 기준으로 제공합니다. partial-coverage 재설계 규약(#56)을 따릅니다 — sub_category 미지정 시 전체 투자자를 long-format으로, 지정 시 해당 투자자 단일 시계열만 반환합니다.

Parameters:

Name	Type	Description	Default
`action`	`str`	거래 행위 - '순매수': 순매수(매수-매도) (기본값) - '매수': 매수 - '매도': 매도	`'순매수'`
`metric`	`str`	측정 지표 - '거래대금': 금액 기준 (기본값) - '거래량': 수량 기준	`'거래대금'`
`sub_category`	`str`	특정 투자자(항목명 또는 item_code1)를 선택합니다. 지정 시 해당 투자자 단일 시계열만 반환합니다. 미지정 시 전체 투자자를 long-format으로 반환합니다. 항목명은 ECOS 라벨(예: '개인(순매수)')을 따르며, 안정적 선택을 위해 item_code(예: 'S22CB')도 허용합니다.	`None`
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식 (월 `YYYYMM` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`frequency`	`str`	조회 주기. `'monthly'`(기본)/`'annual'`. 이 통계표(`901Y055`)는 월·연 자료만 제공합니다.	`'monthly'`

Returns:

Type	Description
`DataFrame`	`sub_category` 미지정: 컬럼 `date, category_value, value, unit` (투자자별 long-format, `category_value`=투자자명). 전체 합계행은 제외. `sub_category` 지정: 컬럼 `date, value, unit` (단일 시계열)

Raises:

Type	Description
`ValueError`	action/metric/frequency가 허용 값이 아니거나, 지정한 `sub_category` 가 존재하지 않는 경우 (사용 가능 항목을 함께 안내).

Notes

외국인 순매수: 외국인 투자자의 매수 - 매도
기관 순매수: 기관 투자자의 매수 - 매도
개인 순매수: 개인 투자자의 매수 - 매도
category_value 는 ECOS 원본 라벨이라 각주 표식이 붙을 수 있습니다 (예: '외국인(순매수) 3)'). 정확한 이름 매칭이 까다로우므로 단일 투자자 선택은 item_code(예: 'S22CC')를 권장합니다.

외국인과 기관의 순매수/순매도는 주가 방향성의 중요한 신호로 활용됩니다.

Examples:

>>> import ecos
>>> # 투자자별 순매수 거래대금 (long-format)
>>> df = ecos.get_investor_trading()
>>> df.head()
        date  category_value   value unit

>>> # 외국인 순매수만
>>> df = ecos.get_investor_trading(sub_category="S22CC")

>>> # 투자자별 매수 거래량
>>> df = ecos.get_investor_trading(action="매수", metric="거래량")

>>> # 연간 투자자별 순매수
>>> df = ecos.get_investor_trading(frequency="annual")

실물경기 지표¶

get_industrial_production ¶

get_industrial_production(start_date: str | None = None, end_date: str | None = None, seasonal: bool = False, frequency: Literal['monthly', 'quarterly', 'annual'] = 'monthly') -> pd.DataFrame

전산업생산지수를 조회합니다.

ECOS 통계표 901Y033(전산업생산지수, 농림어업 제외)을 사용합니다. 월/분기/연별 지수(기준 2020=100)입니다. 2-축 구조(지수 × 계열)이므로 계열을 원계열/계절조정 중 하나로 고정해 단일 시계열을 반환합니다.

Parameters:

Name	Type	Description	Default
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식 (월 `YYYYMM` / 분기 `YYYYQn` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`seasonal`	`bool`	`True` 면 계절조정 계열, `False` 면 원계열(기본).	`False`
`frequency`	`str`	조회 주기. `'monthly'`(기본)/`'quarterly'`/`'annual'`.	`'monthly'`

Returns:

Type	Description
`DataFrame`	컬럼: `date`, `value`, `unit`. `value` 는 지수(2020=100).

Raises:

Type	Description
`ValueError`	지원하지 않는 `frequency` 일 때.

Examples:

>>> import ecos
>>> df = ecos.get_industrial_production()                 # 원계열(월)
>>> df = ecos.get_industrial_production(seasonal=True)    # 계절조정
>>> df = ecos.get_industrial_production(frequency="annual")

get_facility_investment ¶

get_facility_investment(start_date: str | None = None, end_date: str | None = None, seasonal: bool = False, frequency: Literal['monthly', 'quarterly', 'annual'] = 'monthly') -> pd.DataFrame

설비투자지수를 조회합니다.

ECOS 통계표 901Y066(설비투자지수)을 사용합니다. 월/분기/연별 지수(기준 2020=100)이며, 원지수/계절조정지수 중 하나를 반환합니다.

Parameters:

Name	Type	Description	Default
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식 (월 `YYYYMM` / 분기 `YYYYQn` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`seasonal`	`bool`	`True` 면 계절조정지수, `False` 면 원지수(기본).	`False`
`frequency`	`str`	조회 주기. `'monthly'`(기본)/`'quarterly'`/`'annual'`.	`'monthly'`

Returns:

Type	Description
`DataFrame`	컬럼: `date`, `value`, `unit`. `value` 는 지수(2020=100).

Raises:

Type	Description
`ValueError`	지원하지 않는 `frequency` 일 때.

Examples:

>>> import ecos
>>> df = ecos.get_facility_investment()
>>> df = ecos.get_facility_investment(frequency="annual")

get_composite_index ¶

get_composite_index(index: Literal['leading', 'coincident', 'lagging'] = 'coincident', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

경기종합지수(CI)를 조회합니다.

ECOS 통계표 901Y067(경기종합지수)의 선행/동행/후행 종합지수를 조회합니다. 월별 지수(기준 2020=100)입니다.

Parameters:

Name	Type	Description	Default
`index`	`str`	조회할 지수. - `'coincident'`: 동행종합지수 (기본값) - `'leading'`: 선행종합지수 - `'lagging'`: 후행종합지수	`'coincident'`
`start_date`	`str`	조회 시작월 (`YYYYMM` 형식). 기본값: 24개월 전.	`None`
`end_date`	`str`	조회 종료월 (`YYYYMM` 형식). 기본값: 현재.	`None`

Returns:

Type	Description
`DataFrame`	컬럼: `date`, `value`, `unit`. `value` 는 지수(2020=100).

Raises:

Type	Description
`ValueError`	지원하지 않는 `index` 일 때.

Examples:

>>> import ecos
>>> df = ecos.get_composite_index("leading")

get_retail_sales ¶

get_retail_sales(index: Literal['nominal', 'real', 'seasonal'] = 'real', sub_category: str | None = None, start_date: str | None = None, end_date: str | None = None, frequency: Literal['monthly', 'quarterly', 'annual'] = 'monthly') -> pd.DataFrame

소매판매액지수를 상품군별로 조회합니다.

ECOS 통계표 901Y100(재별 및 상품군별 판매액지수)을 조회합니다. 2-축 구조 (상품군 item_code1 × 지수 계열 item_code2)로, index 로 계열을 고정한 뒤 partial-coverage 규약(#56)에 따라 sub_category 미지정 시 전체 상품군을 long-format으로, 지정 시 해당 상품군 단일 시계열만 반환합니다. 기준 2020=100.

Parameters:

Name	Type	Description	Default
`index`	`str`	지수 계열. - `'real'`: 불변지수 (기본값, 물량 기준) - `'nominal'`: 경상지수 (금액 기준) - `'seasonal'`: 계절조정지수	`'real'`
`sub_category`	`str`	상품군(분류명 또는 item_code1). 지정 시 해당 상품군 단일 시계열만, 미지정 시 전체 상품군을 long-format으로 반환합니다. 예) '총지수', '내구재', '음식료품', 또는 item_code 'G31'.	`None`
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식 (월 `YYYYMM` / 분기 `YYYYQn` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`frequency`	`str`	조회 주기. `'monthly'`(기본)/`'quarterly'`/`'annual'`.	`'monthly'`

Returns:

Type	Description
`DataFrame`	`sub_category` 미지정: 컬럼 `date, category_value, value, unit` (상품군별 long-format, `category_value`=상품군명). 통계표는 계층형 (총지수+내구재/준내구재/비내구재+세부품목)이라 단순 합산은 금지. `sub_category` 지정: 컬럼 `date, value, unit` (단일 시계열). value 는 지수(2020=100).

Raises:

Type	Description
`ValueError`	지원하지 않는 `index`/`frequency` 이거나 `sub_category` 가 없을 때.

Examples:

>>> import ecos
>>> df = ecos.get_retail_sales()                          # 전체 상품군 long-format(불변지수, 월)
>>> df = ecos.get_retail_sales(sub_category="총지수")       # 총지수 단일 시계열
>>> df = ecos.get_retail_sales("nominal", sub_category="음식료품", frequency="annual")

심리 지표¶

get_business_sentiment ¶

get_business_sentiment(sector: Literal['all', 'manufacturing', 'heavy_chemical', 'light', 'large', 'sme', 'export', 'domestic', 'non_manufacturing', 'service'] = 'all', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

기업경기실사지수(BSI) — 업황전망BSI를 조회합니다.

ECOS 통계표 512Y014(기업경기조사, 전망)의 업황전망BSI(헤드라인)를 업종별로 조회합니다. 월별 지수이며, 100을 기준으로 그 이상이면 경기를 긍정적으로 보는 기업이 더 많음을 뜻합니다.

Parameters:

Name	Type	Description	Default
`sector`	`str`	조회 업종 (전 부문 라이브 검증, #154). - `'all'`: 전산업 (기본값) - `'manufacturing'`: 제조업 / `'heavy_chemical'`: 중화학공업 / `'light'`: 경공업 - `'large'`: 대기업 / `'sme'`: 중소기업 / `'export'`: 수출기업 / `'domestic'`: 내수기업 - `'non_manufacturing'`: 비제조업 / `'service'`: 서비스업	`'all'`
`start_date`	`str`	조회 시작월 (`YYYYMM` 형식). 기본값: 24개월 전.	`None`
`end_date`	`str`	조회 종료월 (`YYYYMM` 형식). 기본값: 현재.	`None`

Returns:

Type	Description
`DataFrame`	컬럼: `date`, `value`, `unit`. - `value`: 업황전망BSI (지수, 기준 100)

Raises:

Type	Description
`ValueError`	지원하지 않는 `sector` 일 때.

Notes

512Y014는 2-축 구조(업종 × 설문항목)입니다. 이 함수는 설문항목을 업황전망 BSI(BA)로 고정합니다. 매출/생산/자금사정 등 세부 항목은 ecos.get_series("512Y014", "M", item_code=[sector, code2], ...) 로 조회하세요.

Examples:

>>> import ecos
>>> df = ecos.get_business_sentiment("manufacturing")

get_consumer_sentiment ¶

get_consumer_sentiment(start_date: str | None = None, end_date: str | None = None, sub_category: str | None = None) -> pd.DataFrame

소비자심리지수(CSI)를 조회합니다.

ECOS 통계표 511Y002(소비자동향조사)를 조회합니다. 월별 지수이며, 100을 기준으로 그 이상이면 소비 심리가 낙관적임을 뜻합니다. 기본은 종합 소비자심리 지수(FME)이며, sub_category 로 구성지표(생활형편전망·소비지출전망 등)를 선택할 수 있습니다. 인구통계 축(item_code2)은 '전체'로 고정합니다.

Parameters:

Name	Type	Description	Default
`start_date`	`str`	조회 시작월 (`YYYYMM` 형식). 기본값: 24개월 전.	`None`
`end_date`	`str`	조회 종료월 (`YYYYMM` 형식). 기본값: 현재.	`None`
`sub_category`	`str`	구성지표(분류명 또는 item_code1). 미지정 시 종합 소비자심리지수(FME). 예) '소비지출전망CSI', '생활형편전망CSI', 또는 item_code 'FMCB'.	`None`

Returns:

Type	Description
`DataFrame`	컬럼: `date`, `value`, `unit`. `value` 는 지수(기준 100). (단일 시계열 — 종합 또는 선택한 구성지표 1개)

Notes

511Y002는 2-축 구조(구성지표 × 인구통계)입니다. 이 함수는 인구통계를 '전체'로 고정합니다. 성별·연령·소득 등 인구통계별 세부는 ecos.get_series("511Y002", "M", item_code=[code1, demo], ...) 로 조회하세요.

Examples:

>>> import ecos
>>> df = ecos.get_consumer_sentiment()                          # 종합 CSI
>>> df = ecos.get_consumer_sentiment(sub_category="소비지출전망CSI")

환율 지표¶

get_exchange_rate ¶

get_exchange_rate(currency: Literal['USD', 'JPY', 'EUR', 'CNY'] = 'USD', start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

원/외화 환율(매매기준율)을 조회합니다.

ECOS 통계표 731Y001(주요국 통화의 대원화환율, 일별)을 사용합니다. 이 표는 일별 종가의 정본이며, 통화별 매매기준율을 제공합니다.

Parameters:

Name	Type	Description	Default
`currency`	`str`	통화 코드. - `'USD'`: 원/미국달러 (기본값) - `'JPY'`: 원/일본엔 — 100엔당 환율입니다. - `'EUR'`: 원/유로 - `'CNY'`: 원/위안 (2016-01-04~)	`'USD'`
`start_date`	`str`	조회 시작일 (`YYYYMMDD` 형식), 기본값: 1년 전.	`None`
`end_date`	`str`	조회 종료일 (`YYYYMMDD` 형식), 기본값: 현재.	`None`

Returns:

Type	Description
`DataFrame`	컬럼: `date`, `value`, `unit`. - `date`: 날짜 (datetime) - `value`: 환율 (원). 환율은 영업일에만 갱신되어 결과가 sparse 합니다. - `unit`: 단위 (원)

Raises:

Type	Description
`ValueError`	지원하지 않는 `currency` 일 때.

Examples:

>>> import ecos
>>> df = ecos.get_exchange_rate("USD")
>>> df.head(1)
        date   value unit
0 2024-01-02  1289.4    원

>>> # 기간 지정
>>> df = ecos.get_exchange_rate("JPY", start_date="20240101", end_date="20241231")

국제수지 지표¶

get_balance_of_payments ¶

get_balance_of_payments(account: Literal['current', 'capital', 'financial'] = 'current', start_date: str | None = None, end_date: str | None = None, frequency: Literal['monthly', 'quarterly', 'annual'] = 'monthly') -> pd.DataFrame

국제수지(BoP) 주요 계정 시계열을 조회합니다.

ECOS 통계표 301Y013(국제수지)을 사용합니다. 단위는 백만달러이며, 월/분기/연 주기를 지원합니다.

Parameters:

Name	Type	Description	Default
`account`	`str`	조회할 계정. - `'current'`: 경상수지 (기본값) - `'capital'`: 자본수지 - `'financial'`: 금융계정	`'current'`
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식 (월 `YYYYMM` / 분기 `YYYYQn` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`frequency`	`str`	조회 주기. - `'monthly'`: 월별 (기본값) - `'quarterly'`: 분기별 - `'annual'`: 연별	`'monthly'`

Returns:

Type	Description
`DataFrame`	컬럼: `date`, `value`, `unit`. - `value`: 수지 (백만달러). 흑자는 양수, 적자는 음수.

Raises:

Type	Description
`ValueError`	지원하지 않는 `account` 또는 `frequency` 일 때.

Examples:

>>> import ecos
>>> df = ecos.get_balance_of_payments("current")  # 월별 경상수지
>>> df = ecos.get_balance_of_payments("financial", frequency="annual")

무역 지표¶

get_trade ¶

get_trade(flow: Literal['export', 'import'] = 'export', start_date: str | None = None, end_date: str | None = None, frequency: Literal['monthly', 'annual'] = 'monthly') -> pd.DataFrame

수출입 금액(통관 기준)을 조회합니다.

ECOS 통계표 901Y118(수출입 총괄)을 사용합니다. 단위는 천불(천 USD)이며 월/연 주기를 지원합니다.

Parameters:

Name	Type	Description	Default
`flow`	`str`	조회 항목. - `'export'`: 수출금액 (기본값) - `'import'`: 수입금액	`'export'`
`start_date`	`str`	조회 시작 시점. `frequency` 에 맞는 형식(월 `YYYYMM` / 연 `YYYY`). 기본값: 주기별 기본 범위.	`None`
`end_date`	`str`	조회 종료 시점. (형식은 `start_date` 와 동일)	`None`
`frequency`	`str`	조회 주기. `'monthly'`(기본) 또는 `'annual'`.	`'monthly'`

Returns:

Type	Description
`DataFrame`	컬럼: `date`, `value`, `unit`. `value` 는 금액(천불).

Raises:

Type	Description
`ValueError`	지원하지 않는 `flow` 또는 `frequency` 일 때.

Examples:

>>> import ecos
>>> df = ecos.get_trade("export")                       # 월별 수출금액
>>> df = ecos.get_trade("import", frequency="annual")   # 연별 수입금액

지표 레지스트리¶

list_indicators ¶

list_indicators() -> list[IndicatorSpec]

등록된 모든 지표 spec을 이름순으로 반환합니다.

get_indicator ¶

get_indicator(name: str, start_date: str | None = None, end_date: str | None = None) -> pd.DataFrame

레지스트리에 등록된 단일 지표를 이름으로 조회합니다.

Parameters:

Name	Type	Description	Default
`name`	`str`	:data:`INDICATORS` 의 키 (예: `"cpi"`, `"fiscal_balance"`).	required
`start_date`	`str`	조회 시작일. 주기에 맞춘 형식(M=YYYYMM 등). 기본값은 spec의 lookback.	`None`
`end_date`	`str`	조회 종료일. 기본값은 현재.	`None`

Returns:

Type	Description
`DataFrame`	컬럼: date, value, unit.

Raises:

Type	Description
`ValueError`	`name` 이 레지스트리에 없을 때. 사용 가능한 이름 목록을 함께 안내합니다.

Examples:

>>> import ecos
>>> df = ecos.get_indicator("cpi", start_date="202301", end_date="202312")