통계 조회 조건 설정 개발 명세서

개요

한국은행 경제통계 Open API의 실제 통계 데이터를 조회하는 핵심 서비스입니다. 통계표코드, 주기, 기간, 통계항목코드를 지정하여 시계열 통계 데이터를 조회할 수 있습니다.

상세주소

• https://ecos.bok.or.kr/api/
• HTTP와 HTTPS 모두 사용 가능합니다.

요청인자

항목명(국문)	필수여부	샘플데이터	항목설명
서비스명	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	2020	검색시작일자(주기에 맞는 형식으로 입력)
검색종료일자	Y	2023	검색종료일자(주기에 맞는 형식으로 입력)
통계항목코드1	N	10101	통계항목코드1
통계항목코드2	N	?	통계항목코드2
통계항목코드3	N	?	통계항목코드3
통계항목코드4	N	?	통계항목코드4

요청인자 설명

• 서비스명: 고정값 StatisticSearch
• 인증키: 한국은행 Open API에서 발급받은 인증키
• 요청유형: 응답 형식 (xml 또는 json)
• 언어구분: 응답 언어 (kr: 국문, en: 영문)
• 요청시작건수: 페이징을 위한 시작 번호 (1부터 시작)
• 요청종료건수: 페이징을 위한 종료 번호
• 통계표코드: 조회할 통계표의 코드 (필수, 예: 200Y101)
• 주기: 데이터 주기 (필수)
• A: 연간
• S: 반년
• Q: 분기
• M: 월간
• SM: 반월
• D: 일간
• 검색시작일자: 조회 시작일자 (필수, 주기에 맞는 형식)
• 검색종료일자: 조회 종료일자 (필수, 주기에 맞는 형식)
• 통계항목코드1~4: 조회할 통계항목 코드 (선택사항, 최대 4개)

날짜 형식 가이드

주기에 따라 날짜 형식이 달라집니다:

주기	날짜 형식	예시
A (연간)	YYYY	2020, 2023
S (반년)	YYYYS	2020S1, 2020S2
Q (분기)	YYYYQN	2020Q1, 2023Q4
M (월간)	YYYYMM	202001, 202312
SM (반월)	YYYYMMSM	202001SM1, 202001SM2
D (일간)	YYYYMMDD	20200101, 20231231

출력값

항목명(국문)	항목명(영문)	항목크기	샘플데이터	항목설명
통계표코드	STAT_CODE	8	200Y101	통계표코드
통계명	STAT_NAME	200	2.1.1.1. 주요지표(연간지표)	통계명
통계항목코드1	ITEM_CODE1	20	10101	통계항목코드1
통계항목명1	ITEM_NAME1	200	국내총생산(명목, 원화표시)	통계항목명1
통계항목코드2	ITEM_CODE2	20	null	통계항목코드2
통계항목명2	ITEM_NAME2	200	null	통계항목명2
통계항목코드3	ITEM_CODE3	20	null	통계항목코드3
통계항목명3	ITEM_NAME3	200	null	통계항목명3
통계항목코드4	ITEM_CODE4	20	null	통계항목코드4
통계항목명4	ITEM_NAME4	200	null	통계항목명4
단위	UNIT_NAME	200	십억원	단위
가중치	WGT	22	null	가중치
시점	TIME	8	2020	시점
값	DATA_VALUE	23	1658020.4	값

출력값 설명

• 통계표코드: 조회된 통계표의 고유 코드
• 통계명: 통계표의 전체 이름
• 통계항목코드1~4: 조회된 통계항목의 코드 (사용한 항목만 값이 있음)
• 통계항목명1~4: 조회된 통계항목의 이름 (사용한 항목만 값이 있음)
• 단위: 데이터의 단위 (예: 십억원, %, 명 등)
• 가중치: 해당 항목의 가중치 값 (없을 경우 null)
• 시점: 데이터의 시점 (주기에 맞는 형식)
• 값: 실제 통계 데이터 값

샘플 URL

https://ecos.bok.or.kr/api/StatisticSearch/{인증키}/xml/kr/1/10/200Y101/A/2020/2023/10101

URL 구성 요소

1. 기본 URL: https://ecos.bok.or.kr/api/
2. 서비스명: StatisticSearch
3. 인증키: {인증키} (실제 인증키로 대체)
4. 요청유형: xml 또는 json
5. 언어구분: kr 또는 en
6. 요청시작건수: 1
7. 요청종료건수: 10
8. 통계표코드: 조회할 통계표코드 (예: 200Y101)
9. 주기: 데이터 주기 (예: A)
10. 검색시작일자: 조회 시작일자 (예: 2020)
11. 검색종료일자: 조회 종료일자 (예: 2023)
12. 통계항목코드1: 선택사항 (예: 10101)
13. 통계항목코드2~4: 선택사항 (사용하지 않으면 생략)

메시지 설명

정보 메시지

코드	설명
100	인증키가 유효하지 않습니다. 인증키를 확인하십시오! 인증키가 없는 경우 인증키를 신청하십시오!
200	해당하는 데이터가 없습니다.

에러 메시지

코드	설명
100	필수 값이 누락되어 있습니다. 필수 값을 확인하십시오! 필수 값이 누락되어 있으면 오류를 발생합니다. 요청 변수를 참고 하십시오!
101	주기와 다른 형식의 날짜 형식입니다.
200	파일타입 값이 누락 혹은 유효하지 않습니다. 파일타입 값을 확인하십시오! 파일타입 값이 누락 혹은 유효하지 않으면 오류를 발생합니다. 요청 변수를 참고 하십시오!
300	조회건수 값이 누락되어 있습니다. 조회시작건수/조회종료건수 값을 확인하십시오! 조회시작건수/조회종료건수 값이 누락되어 있으면 오류를 발생합니다.
301	조회건수 값의 타입이 유효하지 않습니다. 조회건수 값을 확인하십시오! 조회건수 값의 타입이 유효하지 않으면 오류를 발생합니다. 정수를 입력하세요.
400	검색범위가 적정범위를 초과하여 60초 TIMEOUT이 발생하였습니다. 요청조건 조정하여 다시 요청하시기 바랍니다.
500	서버 오류입니다. OpenAPI 호출시 서버에서 오류가 발생하였습니다. 해당 서비스를 찾을 수 없습니다.
600	DB Connection 오류입니다. OpenAPI 호출시 서버에서 DB접속 오류가 발생했습니다.
601	SQL 오류입니다. OpenAPI 호출시 서버에서 SQL 오류가 발생했습니다.
602	과도한 OpenAPI호출로 이용이 제한되었습니다. 잠시후 이용해주시기 바랍니다.

사용 예제

연간 데이터 조회 (주기: A)

curl "https://ecos.bok.or.kr/api/StatisticSearch/YOUR_API_KEY/xml/kr/1/10/200Y101/A/2020/2023/10101"

분기 데이터 조회 (주기: Q)

curl "https://ecos.bok.or.kr/api/StatisticSearch/YOUR_API_KEY/xml/kr/1/10/200Y101/Q/2020Q1/2023Q4/10101"

월간 데이터 조회 (주기: M)

curl "https://ecos.bok.or.kr/api/StatisticSearch/YOUR_API_KEY/xml/kr/1/10/200Y101/M/202001/202312/10101"

일간 데이터 조회 (주기: D)

curl "https://ecos.bok.or.kr/api/StatisticSearch/YOUR_API_KEY/xml/kr/1/10/200Y101/D/20200101/20231231/10101"

여러 통계항목 조회

# 통계항목코드1과 통계항목코드2를 함께 조회
curl "https://ecos.bok.or.kr/api/StatisticSearch/YOUR_API_KEY/xml/kr/1/10/200Y101/A/2020/2023/10101/10102"

JSON 형식 요청

curl "https://ecos.bok.or.kr/api/StatisticSearch/YOUR_API_KEY/json/kr/1/10/200Y101/A/2020/2023/10101"

Python 예제

import requests
import urllib.parse

api_key = "YOUR_API_KEY"
stat_code = "200Y101"
cycle = "A"  # 연간
start_date = "2020"
end_date = "2023"
item_code1 = "10101"

base_url = "https://ecos.bok.or.kr/api/StatisticSearch"
url = f"{base_url}/{api_key}/xml/kr/1/10/{stat_code}/{cycle}/{start_date}/{end_date}/{item_code1}"

response = requests.get(url)
print(response.text)

Python 예제 - 월간 데이터

import requests

api_key = "YOUR_API_KEY"
stat_code = "200Y101"
cycle = "M"  # 월간
start_date = "202001"
end_date = "202312"
item_code1 = "10101"

base_url = "https://ecos.bok.or.kr/api/StatisticSearch"
url = f"{base_url}/{api_key}/xml/kr/1/10/{stat_code}/{cycle}/{start_date}/{end_date}/{item_code1}"

response = requests.get(url)
data = response.text
print(data)

주의사항

1. 인증키: 모든 요청에 유효한 인증키가 필요합니다.
2. 통계표코드 필수: 통계표코드는 필수 파라미터이며, 유효한 통계표코드를 입력해야 합니다.
3. 주기와 날짜 형식 일치: 주기에 맞는 날짜 형식을 사용해야 합니다. 형식이 맞지 않으면 에러-101이 발생합니다.
4. 통계항목코드 확인: 통계항목코드는 통계 세부항목 목록 API를 통해 확인할 수 있습니다.
5. 페이징: 요청시작건수와 요청종료건수는 필수이며, 정수값이어야 합니다.
6. 타임아웃: 조회 기간이 너무 길거나 항목이 많으면 60초 타임아웃이 발생할 수 있습니다. 기간을 나누어 조회하세요.
7. 호출 제한: 과도한 호출 시 일시적으로 이용이 제한될 수 있습니다.
8. null 값: 통계항목코드2~4와 통계항목명2~4, 가중치는 사용하지 않은 경우 null입니다.
9. 날짜 범위: 검색시작일자는 검색종료일자보다 이전이어야 합니다.
10. 통계항목코드 선택: 통계항목코드를 지정하지 않으면 해당 통계표의 모든 항목이 조회될 수 있습니다.

사용 시나리오

1. 통계표 선택: 서비스 통계 목록 API로 원하는 통계표를 찾습니다.
2. 항목 확인: 통계 세부항목 목록 API로 해당 통계표의 세부 항목과 주기, 수록기간을 확인합니다.
3. 데이터 조회: 이 API를 사용하여 실제 통계 데이터를 조회합니다.
4. 통계표코드, 주기, 기간을 지정
5. 필요한 경우 통계항목코드를 지정하여 특정 항목만 조회

주기별 날짜 형식 상세 가이드

연간 (A)

• 형식: YYYY
• 예시: 2020, 2023
• 범위: 2020 ~ 2023

반년 (S)

• 형식: YYYYSN (N은 1 또는 2)
• 예시: 2020S1, 2020S2, 2023S1
• 범위: 2020S1 ~ 2023S2

분기 (Q)

• 형식: YYYYQN (N은 1, 2, 3, 4)
• 예시: 2020Q1, 2020Q2, 2023Q4
• 범위: 2020Q1 ~ 2023Q4

월간 (M)

• 형식: YYYYMM
• 예시: 202001, 202012, 202312
• 범위: 202001 ~ 202312

반월 (SM)

• 형식: YYYYMMSMN (N은 1 또는 2)
• 예시: 202001SM1, 202001SM2
• 범위: 202001SM1 ~ 202312SM2

일간 (D)

• 형식: YYYYMMDD
• 예시: 20200101, 20201231, 20231231
• 범위: 20200101 ~ 20231231

관련 서비스

• 서비스 통계 목록 - 통계표 목록 조회
• 통계 세부항목 목록 - 통계표의 세부 항목 조회
• 통계용어사전 - 통계 용어 검색
• 100대 통계지표 - 주요 통계지표 조회