🚀 2025년 10월 최신판: 한국은행 ECOS API 완벽 마스터 가이드

 

경제 데이터의 보물창고를 여는 6가지 핵심 서비스 총정리

---

📊 ECOS API란?

한국은행 경제통계시스템(ECOS, Economic Statistics System)은 한국은행이 제공하는 경제통계 데이터를 Open API 형태로 제공하는 서비스입니다. 개발자와 연구자들이 실시간 경제 데이터를 프로그래밍 방식으로 쉽게 접근하고 활용할 수 있도록 지원해요.

GDP, 물가지수, 환율, 금리 등 다양한 경제 지표를 무료로 이용할 수 있어서, 경제 분석이나 투자 전략 수립에 아주 유용하답니다!

---

🚀 시작하기

1. API 인증키 발급

API 서비스를 이용하기 위해서는 먼저 인증키가 필요합니다.

발급 절차:

1. 한국은행 ECOS 웹사이트 접속
2. Open API 메뉴 클릭
3. 회원가입 및 인증키 신청
4. 가입 즉시 인증키 자동 부여 (일반적으로 1일 이내 API 호출 가능)

💡 Tip: 테스트용으로는 sample이라는 인증키를 사용할 수 있어요. 실제 프로젝트에는 본인의 인증키를 발급받아 사용하세요!

2. API URL 구조

ECOS API의 기본 URL 구조는 다음과 같습니다:

기본 주소: https://ecos.bok.or.kr/api/ (https와 http 모두 사용 가능)

전체 구조:

https://ecos.bok.or.kr/api/[서비스명]/[인증키]/[요청유형]/[언어구분]/[요청시작건수]/[요청종료건수]/[통계표코드]/[주기]/[검색시작일자]/[검색종료일자]/[항목코드1]/[항목코드2]/[항목코드3]

예시:

https://ecos.bok.or.kr/api/StatisticSearch/sample/json/kr/1/10/200Y101/A/2024/2025/10101

---

📝 주요 서비스 목록

ECOS API는 6가지 핵심 서비스를 제공합니다.

1. StatisticTableList - 통계 테이블 목록 조회

제공되는 모든 통계 테이블의 목록을 확인할 수 있어요. 어떤 데이터가 있는지 먼저 확인할 때 유용합니다.

2. StatisticSearch - 통계 시계열 조회 ⭐

개별 통계의 시계열 데이터를 조회하는 가장 중요한 서비스예요. 실제 경제 데이터를 받아오는 핵심 기능입니다.

3. KeyStatisticList - 100대 통계지표 조회

한국은행이 선정한 100대 주요 경제지표를 한 번에 조회할 수 있어요.

4. StatisticMeta - 통계 메타정보 조회

각 통계의 상세 설명, 단위, 주기 등의 메타정보를 제공합니다.

5. StatisticWord - 통계용어사전

경제통계 관련 용어의 정의와 설명을 조회할 수 있어요.

6. StatisticItemList - 통계 세부항목 목록 조회

특정 통계의 세부 항목 목록을 조회할 수 있습니다.

---

📋 1. StatisticTableList 서비스

서비스 개요

통계 테이블 목록을 조회하는 서비스로, 한국은행 ECOS에서 제공하는 모든 통계표의 목록과 메타정보를 확인할 수 있어요.

요청 인자 (Request Parameters)

항목명 필수여부 샘플데이터 항목설명

서비스명	Y	StatisticTableList	API 서비스명
인증키	Y	sample	한국은행에서 발급받은 오픈API 인증키
요청유형	Y	xml	결과값의 파일 형식 (xml, json)
언어구분	Y	kr	결과값의 언어 - kr(국문), en(영문)
요청시작건수	Y	1	전체 결과값 중 시작 번호
요청종료건수	Y	10	전체 결과값 중 끝 번호
통계표코드	N	102Y004	특정 통계표코드로 필터링 (선택사항)

출력값 (Output Result)

항목명(국문) 항목명(영문) 샘플데이터 항목설명

상위통계표코드	P_STAT_CODE	0000000442	상위통계표코드
통계표코드	STAT_CODE	102Y004	통계표코드
통계명	STAT_NAME	1.1.1.1.2. 본원통화 구성내역(평잔, 원계열)	통계명
주기	CYCLE	M	주기(년, 분기, 월, 일)
검색가능여부	SRCH_YN	Y	검색가능여부
출처	ORG_NAME	한국은행	출처

샘플 URL 예시

# 전체 통계표 목록 조회 (샘플 인증키 사용)
https://ecos.bok.or.kr/api/StatisticTableList/sample/xml/kr/1/10

# 특정 통계표코드로 필터링
https://ecos.bok.or.kr/api/StatisticTableList/sample/xml/kr/1/10/102Y004

---

📚 2. StatisticWord 서비스

서비스 개요

경제통계 관련 용어의 정의와 상세 설명을 조회하는 서비스예요. 경제 용어에 대한 이해를 돕기 위한 사전 기능을 제공합니다.

요청 인자 (Request Parameters)

항목명 필수여부 샘플데이터 항목설명

서비스명	Y	StatisticWord	API 서비스명
인증키	Y	sample	한국은행에서 발급받은 오픈API 인증키
요청유형	Y	xml	결과값의 파일 형식 (xml, json)
언어구분	Y	kr	결과값의 언어 - kr(국문), en(영문)
요청시작건수	Y	1	전체 결과값 중 시작 번호
요청종료건수	Y	10	전체 결과값 중 끝 번호
용어	Y	소비자동향지수	조회할 용어

출력값 (Output Result)

항목명(국문) 항목명(영문) 샘플데이터 항목설명

용어	WORD	소비자동향지수	용어
용어설명	CONTENT	소비자들이 느끼는 경기, 소비지출계획, 생활형편 등...	용어설명

샘플 URL 예시

# 특정 용어 조회 (소비자동향지수)
https://ecos.bok.or.kr/api/StatisticWord/sample/xml/kr/1/10/소비자동향지수

# JSON 형식으로 용어 조회
https://ecos.bok.or.kr/api/StatisticWord/sample/json/kr/1/10/GDP

---

📊 3. StatisticItemList 서비스

서비스 개요

특정 통계표의 세부 항목 목록을 조회하는 서비스예요. 통계표에 포함된 모든 세부 항목의 코드, 명칭, 계층구조, 수록기간 등을 확인할 수 있습니다.

요청 인자

항목명 필수여부 샘플데이터 항목설명

서비스명	Y	StatisticItemList	API 서비스명
인증키	Y	sample	한국은행에서 발급받은 오픈API 인증키
요청유형	Y	xml	결과값의 파일 형식 (xml, json)
언어구분	Y	kr	결과값의 언어 - kr(국문), en(영문)
요청시작건수	Y	1	전체 결과값 중 시작 번호
요청종료건수	Y	10	전체 결과값 중 끝 번호
통계표코드	Y	601Y002	조회할 통계표코드

출력값

항목명(국문) 항목명(영문) 샘플데이터 항목설명

통계표코드	STAT_CODE	601Y002	통계표코드
통계명	STAT_NAME	7.5.2. 지역별 소비유형별 개인 신용카드	통계명
통계항목코드	ITEM_CODE	A	통계항목코드
통계항목명	ITEM_NAME	서울	통계항목명
주기	CYCLE	M	주기
수록시작일자	START_TIME	200912	수록시작일자
수록종료일자	END_TIME	202410	수록종료일자
자료수	DATA_CNT	180	자료수

샘플 URL 예시

# 특정 통계표의 세부항목 조회
https://ecos.bok.or.kr/api/StatisticItemList/sample/xml/kr/1/10/601Y002

# JSON 형식으로 조회
https://ecos.bok.or.kr/api/StatisticItemList/sample/json/kr/1/50/102Y004

---

💯 4. KeyStatisticList 서비스

서비스 개요

한국은행이 선정한 100대 주요 경제지표를 조회하는 서비스예요. 주요 경제지표의 최신 값과 시점을 한 번에 확인할 수 있습니다.

요청 인자

항목명 필수여부 샘플데이터 항목설명

서비스명	Y	KeyStatisticList	API 서비스명
인증키	Y	sample	한국은행에서 발급받은 오픈API 인증키
요청유형	Y	xml	결과값의 파일 형식 (xml, json)
언어구분	Y	kr	결과값의 언어 - kr(국문), en(영문)
요청시작건수	Y	1	전체 결과값 중 시작 번호
요청종료건수	Y	10	전체 결과값 중 끝 번호

출력값

항목명(국문) 항목명(영문) 샘플데이터 항목설명

통계그룹명	CLASS_NAME	국민소득 · 경기 · 기업경영	통계그룹명
통계명	KEYSTAT_NAME	경제성장률(전기대비)	통계명
값	DATA_VALUE	1.9	값
시점	CYCLE	202503	통계의 최근 수록 시점
단위	UNIT_NAME	%, 달러, 십억원 등	단위

샘플 URL 예시

# 100대 통계지표 조회 (1~10번)
https://ecos.bok.or.kr/api/KeyStatisticList/sample/xml/kr/1/10

# 100대 통계지표 전체 조회 (JSON)
https://ecos.bok.or.kr/api/KeyStatisticList/sample/json/kr/1/100

---

📈 5. StatisticSearch 서비스 ⭐

서비스 개요

통계 조회 조건을 설정하여 시계열 데이터를 조회하는 핵심 서비스예요. 특정 기간의 경제 지표 데이터를 시계열로 조회할 수 있습니다.

요청 인자

항목명 필수여부 샘플데이터 항목설명

서비스명	Y	StatisticSearch	API 서비스명
인증키	Y	sample	한국은행에서 발급받은 오픈API 인증키
요청유형	Y	xml	결과값의 파일 형식 (xml, json)
언어구분	Y	kr	결과값의 언어 - kr(국문), en(영문)
요청시작건수	Y	1	전체 결과값 중 시작 번호
요청종료건수	Y	10	전체 결과값 중 끝 번호
통계표코드	Y	200Y101	통계표코드
주기	Y	A	주기(년:A, 반년:S, 분기:Q, 월:M, 반월:SM, 일:D)
검색시작일자	Y	2023	주기에 맞는 형식 (2023, 2023Q1, 202301, 20230101 등)
검색종료일자	Y	2025	주기에 맞는 형식 (2025, 2025Q1, 202510, 20251031 등)
통계항목코드1	N	10101	첫 번째 통계항목코드
통계항목코드2	N	?	두 번째 통계항목코드

출력값

항목명(국문) 항목명(영문) 샘플데이터 항목설명

통계표코드	STAT_CODE	200Y101	통계표코드
통계명	STAT_NAME	2.1.1.1. 주요지표(연간지표)	통계명
통계항목코드1	ITEM_CODE1	10101	통계항목코드1
통계항목명1	ITEM_NAME1	국내총생산(명목, 원화표시)	통계항목명1
단위	UNIT_NAME	십억원	단위
시점	TIME	2024	시점
값	DATA_VALUE	2345123.4	값

주기별 날짜 형식 예시

주기 코드 날짜 형식 예시

년	A	YYYY	2025
반년	S	YYYYS1/S2	2025S1 (상반기), 2025S2 (하반기)
분기	Q	YYYYQ1-4	2025Q1, 2025Q2, 2025Q3, 2025Q4
월	M	YYYYMM	202501, 202510
반월	SM	YYYYMMDD	20250101 (상반월), 20250115 (하반월)
일	D	YYYYMMDD	20250101, 20251031

샘플 URL 예시

# 연간 GDP 데이터 조회
https://ecos.bok.or.kr/api/StatisticSearch/sample/xml/kr/1/10/200Y101/A/2023/2025/10101

# 월별 환율 데이터 조회 (JSON)
https://ecos.bok.or.kr/api/StatisticSearch/sample/json/kr/1/100/902Y006/M/202501/202510/US

---

🔍 6. StatisticMeta 서비스

서비스 개요

통계메타DB 서비스로, 특정 데이터명에 대한 메타정보를 조회해요. 통계의 작성 배경, 방법론, 시계열 정보 등 상세한 메타데이터를 제공합니다.

요청 인자

항목명 필수여부 샘플데이터 항목설명

서비스명	Y	StatisticMeta	API 서비스명
인증키	Y	sample	한국은행에서 발급받은 오픈API 인증키
요청유형	Y	xml	결과값의 파일 형식 (xml, json)
언어구분	Y	kr	결과값의 언어 - kr(국문), en(영문)
요청시작건수	Y	1	전체 결과값 중 시작 번호
요청종료건수	Y	10	전체 결과값 중 끝 번호
데이터명	Y	경제심리지수	조회할 데이터명

출력값

항목명(국문) 항목명(영문) 샘플데이터 항목설명

레벨	LVL	2	레벨
통계항목코드	CONT_CODE	0000000003	통계항목코드
통계항목명	CONT_NAME	최초작성연도	통계항목명
메타데이터	META_DATA	2012.6월 최초 작성(과거 시계열은 2003.1월부터 제공)	메타데이터

샘플 URL 예시

# 경제심리지수 메타정보 조회
https://ecos.bok.or.kr/api/StatisticMeta/sample/xml/kr/1/10/경제심리지수

# 소비자동향지수 메타정보 조회 (JSON)
https://ecos.bok.or.kr/api/StatisticMeta/sample/json/kr/1/10/소비자동향지수

---

⚠️ 메시지 설명

정보 메시지

• 정보-100: 인증키가 유효하지 않습니다. 인증키를 확인하십시오!
• 정보-200: 해당하는 데이터가 없습니다.

에러 메시지

• 에러-100: 필수 값이 누락되어 있습니다.
• 에러-101: 주기와 다른 형식의 날짜 형식입니다.
• 에러-200: 파일타입 값이 누락 혹은 유효하지 않습니다.
• 에러-300: 조회건수 값이 누락되어 있습니다.
• 에러-400: 검색범위가 적정범위를 초과하여 60초 TIMEOUT이 발생하였습니다.
• 에러-602: 과도한 OpenAPI호출로 이용이 제한되었습니다.

---

💻 실제 사용 예시

Python을 이용한 API 호출

1. StatisticTableList 호출

import requests
import json

# API 설정
api_key = "YOUR_API_KEY"  # 테스트시 "sample" 사용 가능
service = "StatisticTableList"
file_type = "json"
language = "kr"
start_count = "1"
end_count = "10"
stat_code = "102Y004"  # 선택사항

# URL 구성
url = f"https://ecos.bok.or.kr/api/{service}/{api_key}/{file_type}/{language}/{start_count}/{end_count}/{stat_code}"

# API 호출
response = requests.get(url)
if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2, ensure_ascii=False))
else:
    print(f"Error: {response.status_code}")

2. StatisticSearch 호출 (GDP 데이터)

# 통계 시계열 데이터 조회
service = "StatisticSearch"
stat_code = "200Y101"  # 주요지표(연간지표)
cycle = "A"  # 연간
start_date = "2023"
end_date = "2025"
item_code1 = "10101"  # 국내총생산

url = f"https://ecos.bok.or.kr/api/{service}/{api_key}/json/kr/1/100/{stat_code}/{cycle}/{start_date}/{end_date}/{item_code1}"

response = requests.get(url)
if response.status_code == 200:
    data = response.json()
    # 시계열 데이터 출력
    for item in data['StatisticSearch']['row']:
        print(f"시점: {item['TIME']}")
        print(f"항목: {item['ITEM_NAME1']}")
        print(f"값: {item['DATA_VALUE']} {item['UNIT_NAME']}")
        print("-" * 50)

3. KeyStatisticList 호출 (100대 지표)

# 100대 통계지표 조회
service = "KeyStatisticList"
url = f"https://ecos.bok.or.kr/api/{service}/{api_key}/json/kr/1/100"

response = requests.get(url)
if response.status_code == 200:
    data = response.json()
    # 100대 지표 출력
    for item in data['KeyStatisticList']['row']:
        print(f"그룹: {item['CLASS_NAME']}")
        print(f"지표명: {item['KEYSTAT_NAME']}")
        print(f"값: {item['DATA_VALUE']} {item['UNIT_NAME']}")
        print(f"시점: {item['CYCLE']}")
        print("-" * 50)

---

📊 주요 통계 카테고리

1. 통화/금융

• 통화/유동성
• 금융기관 여수신
• 금리
• 한국은행 주요계정
• 주식/채권/재정

2. 국민계정

• 국민소득통계
• 산업연관표
• 자금순환표
• 국민대차대조표
• 국제수지표

3. 환율/무역

• 환율 (원/달러, 원/엔, 원/유로 등)
• 통관기준 수출입
• 무역지수/교역조건지수
• 외환보유액

4. 물가

• 생산자물가지수
• 소비자물가지수
• 수출입물가지수

5. 경기/기업경영

• 기업경영분석
• 경제심리지수
• 소비자동향지수
• 기업경기실사지수

---

🛠️ 활용 도구 및 라이브러리

Python - PublicDataReader

from PublicDataReader import Ecos

service_key = "YOUR_API_KEY"
api = Ecos(service_key)

# 통계 테이블 목록 조회
df = api.get_statistic_table_list()

# 주요 경제지표 조회
df = api.get_key_statistic_list()

R - ecos 패키지

# 패키지 설치
install.packages("ecos")
library(ecos)

# API 키 설정
ecos.setKey(api_key = "YOUR_API_KEY")

# 데이터 조회
interest_rate <- statSearch(stat_code = "902Y006", item_code1 = "US", cycle = "M")

---

💡 활용 팁

1. 효율적인 데이터 조회

• 대량 데이터 조회 시 요청 건수를 적절히 분할하여 호출
• 자주 사용하는 데이터는 로컬에 캐싱하여 API 호출 최소화

2. 데이터 주기 선택

• A (Annual): 연간 데이터
• Q (Quarterly): 분기별 데이터
• M (Monthly): 월별 데이터
• D (Daily): 일별 데이터

3. 에러 처리

• API 응답 상태 코드 확인 (200: 성공)
• 인증키 유효성 검증
• 날짜 형식 확인 (YYYYMMDD 또는 YYYYMM)

---

📚 참고 자료

• 한국은행 ECOS 공식 웹사이트
• 한국은행 Open API 가이드
• PublicDataReader 공식 문서

---

🔔 주의사항

• API 호출 제한: 과도한 API 호출은 제한될