통계 세부항목 목록 개발 명세서

개요

한국은행 경제통계 Open API의 특정 통계표에 대한 세부 항목 목록을 조회하는 서비스입니다. 통계표코드를 기준으로 해당 통계표의 항목그룹, 통계항목, 주기, 수록기간 등의 상세 정보를 제공합니다.

상세주소

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

요청인자

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

요청인자 설명

• 서비스명: 고정값 StatisticItemList
• 인증키: 한국은행 Open API에서 발급받은 인증키
• 요청유형: 응답 형식 (xml 또는 json)
• 언어구분: 응답 언어 (kr: 국문, en: 영문)
• 요청시작건수: 페이징을 위한 시작 번호 (1부터 시작)
• 요청종료건수: 페이징을 위한 종료 번호
• 통계표코드: 조회할 통계표의 코드 (필수, 예: 601Y002)

출력값

항목명(국문)	항목명(영문)	항목크기	샘플데이터	항목설명
통계표코드	STAT_CODE	8	601Y002	통계표코드
통계명	STAT_NAME	200	7.5.2. 지역별 소비유형별 개인 신용카드	통계명
항목그룹코드	GRP_CODE	20	Group1	통계항목그룹코드
항목그룹명	GRP_NAME	60	지역코드	통계항목그룹명
통계항목코드	ITEM_CODE	20	A	통계항목코드
통계항목명	ITEM_NAME	200	서울	통계항목명
상위통계항목코드	P_ITEM_CODE	8	null	상위통계항목코드
상위통계항목명	P_ITEM_NAME	200	null	상위통계항목명
주기	CYCLE	2	M	주기(년, 분기, 월)
수록시작일자	START_TIME	8	200912	수록시작일자
수록종료일자	END_TIME	8	202112	수록종료일자
자료수	DATA_CNT	22	145	자료수
단위	UNIT_NAME	200	십억원	단위
가중치	WEIGHT	22	null	가중치

출력값 설명

• 통계표코드: 조회된 통계표의 고유 코드
• 통계명: 통계표의 전체 이름
• 항목그룹코드: 통계항목을 그룹화하는 코드
• 항목그룹명: 항목그룹의 이름 (예: 지역코드, 소비유형 등)
• 통계항목코드: 개별 통계항목을 식별하는 코드
• 통계항목명: 통계항목의 이름 (예: 서울, 부산 등)
• 상위통계항목코드: 계층 구조에서 상위 항목의 코드 (없을 경우 null)
• 상위통계항목명: 계층 구조에서 상위 항목의 이름 (없을 경우 null)
• 주기: 데이터 수집 주기 (연, 분기, 월 등)
• 수록시작일자: 해당 항목의 데이터 수록 시작일자 (YYYYMM 형식)
• 수록종료일자: 해당 항목의 데이터 수록 종료일자 (YYYYMM 형식)
• 자료수: 수록된 데이터의 개수
• 단위: 데이터의 단위 (예: 십억원, %, 명 등)
• 가중치: 해당 항목의 가중치 값 (없을 경우 null)

샘플 URL

https://ecos.bok.or.kr/api/StatisticItemList/{인증키}/xml/kr/1/10/601Y002

URL 구성 요소

1. 기본 URL: https://ecos.bok.or.kr/api/
2. 서비스명: StatisticItemList
3. 인증키: {인증키} (실제 인증키로 대체)
4. 요청유형: xml 또는 json
5. 언어구분: kr 또는 en
6. 요청시작건수: 1
7. 요청종료건수: 10
8. 통계표코드: 조회할 통계표코드 (예: 601Y002)

메시지 설명

정보 메시지

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

에러 메시지

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

사용 예제

XML 형식 요청

curl "https://ecos.bok.or.kr/api/StatisticItemList/YOUR_API_KEY/xml/kr/1/10/601Y002"

JSON 형식 요청

curl "https://ecos.bok.or.kr/api/StatisticItemList/YOUR_API_KEY/json/kr/1/10/601Y002"

다양한 통계표코드 예제

# 지역별 소비유형별 개인 신용카드
curl "https://ecos.bok.or.kr/api/StatisticItemList/YOUR_API_KEY/xml/kr/1/10/601Y002"

# 다른 통계표 예제
curl "https://ecos.bok.or.kr/api/StatisticItemList/YOUR_API_KEY/xml/kr/1/10/043Y070"

페이징 처리

# 첫 10개 결과
curl "https://ecos.bok.or.kr/api/StatisticItemList/YOUR_API_KEY/xml/kr/1/10/601Y002"

# 다음 10개 결과
curl "https://ecos.bok.or.kr/api/StatisticItemList/YOUR_API_KEY/xml/kr/11/20/601Y002"

Python 예제

import requests
import urllib.parse

api_key = "YOUR_API_KEY"
stat_code = "601Y002"
base_url = "https://ecos.bok.or.kr/api/StatisticItemList"

url = f"{base_url}/{api_key}/xml/kr/1/10/{stat_code}"
response = requests.get(url)
print(response.text)

주의사항

1. 인증키: 모든 요청에 유효한 인증키가 필요합니다.
2. 통계표코드 필수: 통계표코드는 필수 파라미터이며, 유효한 통계표코드를 입력해야 합니다.
3. 통계표코드 확인: 통계표코드는 서비스 통계 목록 API를 통해 먼저 확인할 수 있습니다.
4. 페이징: 요청시작건수와 요청종료건수는 필수이며, 정수값이어야 합니다.
5. 타임아웃: 통계표의 항목이 많으면 60초 타임아웃이 발생할 수 있습니다. 페이징을 활용하세요.
6. 호출 제한: 과도한 호출 시 일시적으로 이용이 제한될 수 있습니다.
7. null 값: 상위통계항목코드, 상위통계항목명, 가중치 등은 항목에 따라 null일 수 있습니다.
8. 날짜 형식: 수록시작일자와 수록종료일자는 YYYYMM 형식입니다.

사용 시나리오

1. 통계표 선택: 서비스 통계 목록 API로 원하는 통계표를 찾습니다.
2. 항목 확인: 통계표코드를 사용하여 이 API로 해당 통계표의 세부 항목을 조회합니다.
3. 데이터 조회: 통계항목코드를 사용하여 통계 조회 조건 설정 API로 실제 데이터를 조회합니다.

관련 서비스

• 서비스 통계 목록 - 통계표 목록 조회
• 통계 조회 조건 설정 - 실제 통계 데이터 조회
• 통계용어사전 - 통계 용어 검색
• 100대 통계지표 - 주요 통계지표 조회