PublicDataReader - KOSIS 데이터 조회하기

KOSIS 공유서비스(OpenAPI)

파이썬으로 국가통계포털(KOSIS)에 수록된 데이터를 쉽게 조회할 수 있다.

개요

KOSIS 공유서비스는 외부(기관, 개인)에서 국가통계포털(KOSIS)의 통계정보를 서비스 또는 컨텐츠 개발에 활용할 수 있도록 인터페이스(API)를 제공하는 서비스이다. 통계목록, 통계자료, 대용량 통계자료 그리고 통계설명 서비스를 제공하는 것이 특징이다. 단, 통계자료와 대용량 통계자료의 경우 국제통계 등 라이선스 제약에 해당되는 자료는 서비스에서 제외된다고 한다.

KOSIS 공유서비스 Open API 이용 방법

KOSIS 공유서비스를 활용하려면 KOSIS에 회원 가입해야 한다. 기존 국가통계포털에 회원으로 가입된 사용자는 그대로 사용하면 된다. 인증키는 회원 당 1개 발급되며, 1개 인증키로 모든 서비스를 이용할 수 있다. 참고로, 통계자료의 경우 자료등록 후 데이터를 조회하거나 통계표 선택 후 데이터를 조회할 수 있다. 대용량 통계자료의 경우 자료등록 후 데이터를 조회할 수 있다. API 호출 1회 당 최대 40,000건의 자료를 조회할 수 있다. API 호출 제한은 없다.

Open API 서비스 신청하기

KOSIS 공유서비스에 회원가입 및 로그인 진행 후 활용신청 - 활용신청 탭으로 이동해 Open API 서비스를 신청한다. 자동승인이 되면, 사용자 인증키를 잘 보관한다.

Python으로 KOSIS 데이터 조회하기

PublicDataReader 라이브러리를 이용하면 KOSIS 공유서비스 Open API의 통계목록, 통계자료, 통계설명, 통계표 설명 그리고 KOSIS 통합검색 서비스를 쉽게 이용할 수 있다. PublicDataReader를 설치하고, 데이터를 조회하는 방법에 대해 알아보자.

PublicDataReader 설치하기

• 운영체제(OS)에 따라 아래 중 하나를 선택한다.
  • Windows: CMD(명령 프롬프트) 실행
  • Mac: Terminal(터미널) 실행

아래 Shell 명령어를 입력 후 실행한다.

pip install PublicDataReader --upgrade

PublicDataReader 임포트하기

위에서 설치한 PublicDataReader에서 Kosis 클래스를 임포트합니다.

from PublicDataReader import Kosis

# KOSIS 공유서비스 Open API 사용자 인증키
service_key = "사용자 인증키"

# 인스턴스 생성하기
api = Kosis(service_key)

KOSIS 통합검색

• 요청변수

요청변수	변수타입	설명	비고
searchNm	String	검색명	필수
orgId	String	기관코드	선택
sort	String	정렬 비고 : 정확도 RANK, 최신순DATE ※ 호출 파라미터에 sort 없을 경우에는 자동으로 RANK 로 정렬	선택
startCount	String	페이지 번호	선택
resultCount	String	데이터 출력 개수 비고 : resultCount=20, startCount=1 : 1~20번 결과 리턴 resultCount=20, startCount=2 : 21~40번 결과 리턴	선택

• 출력결과

결과변수	설명
ORG_ID	기관코드
ORG_NM	기관명
TBL_ID	통계표ID
TBL_NM	통계표명
STAT_ID	조사코드
STAT_NM	조사명
VW_CD	KOSIS 목록구분
MT_ATITLE	KOSIS 통계표 위치
FULL_PATH_ID	통계표 위치
CONTENTS	통계표 주요내용
STRT_PRD_DE	수록기간 시작일
END_PRD_DE	수록기간 종료일
ITEM03	통계표 주석
REC_TBL_SE	추천통계표 여부
TBL_VIEW_URL	통계표 이동URL (KOSIS 목록으로 이동)
LINK_URL	통계표 이동URL (KOSIS 통계표로 이동)
STAT_DB_CNT	검색결과 건수
QUERY	검색어명

df1 = api.get_data(
    "KOSIS통합검색",
    searchNm="미분양 현황",
    )
df1.head(1)

	기관ID	기관명	통계표ID	통계표명	조사ID	조사명	KOSIS목록구분	KOSIS통계표위치	통계표위치	통계표주요내용	수록기간시작일	수록기간종료일	통계표주석	추천통계표여부	KOSIS목록URL	KOSIS통계표URL	검색결과건수	검색어명
0	116	국토교통부	DT_MLTM_2086	미분양현황_종합	1998033	미분양주택현황보고	MT_ZTITLE	주거 > 미분양주택현황보고	I1 > I1_2	대분류 구분 부문별미분양현황 시도별미분양현황 규모별미분양현황 세종특별자치시 지방 계...	2001	2021	해당연도 12월말 기준 자료 : 국토교통부 주택토지실 주택정책관 주택정책과	N	https://kosis.kr/statisticsList/statisticsList...	http://kosis.kr/statHtml/statHtml.do?orgId=116...	210	미분양 현황

통계설명

• 요청변수

요청변수	변수타입	설명	비고
statId * orgId(기관ID)+tblId(통계표ID)로도 가능	String	통계조사 ID	필수 예) &statId=통계조사ID 또는 &orgId=기관ID&tblId=통계표ID
metaItm	String	요청 항목	필수 전체 - All 조사명-statsNm 통계종류-statsKind 계속여부-statsContinue 법적근거-basisLaw 조사목적-writingPurps 조사주기-statsPeriod 조사체계-writingSystem 공표범위-pubExtent 공표주기-pubPeriod 연락처-writingTel 통계(활용)분야·실태-statsField 조사 대상범위-examinObjrange 조사 대상지역-examinObjArea 조사단위 및 조사대상규모-josaUnit 적용분류-applyGroup 조사항목-josaItm 공표주기-pubPeriod 공표범위-pubExtent 공표방법 및 URL-publictMth 조사대상기간 및 조사기준시점-examinTrgetPd 자료이용자 유의사항 -dataUserNote 주요 용어해설-mainTermExpl 자료 수집방법-dataCollectMth 조사연혁-examinHistory 승인번호-confmNo 승인일자-confmDt 통계종료-statsEnd

• 출력결과

결과변수	설명
statsNm	조사명
statsKind	통계종류
statsContinue	계속여부
basisLaw	법적근거
writingPurps	조사목적
statsPeriod	조사주기
writingSystem	조사체계
pubExtent	공표범위
pubPeriod	공표주기
writingTel	연락처
statsField	통계(활용)분야·실태
examinObjrange	조사 대상범위
examinObjArea	조사 대상지역
josaUnit	조사단위 및 조사대상규모
applyGroup	적용분류
josaItm	조사항목
pubPeriod	공표주기
pubExtent	공표범위
publictMth	공표방법 및 URL
examinTrgetPd	조사대상기간 및 조사기준시점
dataUserNote	자료이용자 유의사항
mainTermExpl	주요 용어해설
dataCollectMth	자료 수집방법
examinHistory	조사연혁
confmNo	승인번호
confmDt	승인일자
statsEnd	통계종료

df2 = api.get_data(
    "통계설명",
    orgId = "116",
    tblId = "DT_MLTM_2086",
    metaItm = "ALL",
    )
df2.head(1)

	조사명	통계종류	계속여부	법적근거	조사목적	조사주기	조사체계	공표범위	공표주기	연락처	...	조사단위및조사대상규모	적용분류	조사항목	공표방법및URL	조사대상기간및조사기준시점	조사기간	자료수집방법	승인번호	승인일자	통계종료
0	미분양주택현황보고	일반통계 / 보고통계	계속통계	주택법	매월 전국 및 지역별 미분양 주택현황을 파악하여 주택공급정책의 기초자료로 활용	월	구·시·군→시·도→국토교통부	시군구	월	국토교통부 주택토지실 주택정책관 주택정책과 (☎ 044-201-3336)	...	기타전국의 미분양 주택 현황	(주) 해당없음	∎ 작성항목(2개 부문 6개항목) - 전체 미분양 현황: 지역별(광역시/시군구) 세...	전산망(인터넷), 간행물http://stat.molit.go.kr)국토교통통계연보(...	1월1일~12월31일(매월말)	매월 1일~15일	행정집계	116025	19981013	일반통계

1 rows × 22 columns

통계표 설명

통계표 명칭

• 요청변수

요청변수	변수타입	설명	비고
orgId	String	기관코드	필수
tblId	String	통계표ID	필수

• 출력결과

결과변수	설명
TBL_NM	통계표 국문명
TBL_NM_ENG	통계표 영문명

df3_1 = api.get_data(
    "통계표설명",
    "통계표명칭",
    orgId = "116",
    tblId = "DT_MLTM_2086",
    )
df3_1.head(1)

	통계표명	통계표영문명
0	미분양현황_종합	Unsold Housings (Total)

기관 명칭

• 요청변수

요청변수	변수타입	설명	비고
orgId	String	기관코드	필수

• 출력결과

결과변수	설명
ORG_NM	기관 국문명
ORG_NM_ENG	기관 영문명

df3_2 = api.get_data(
    "통계표설명",
    "기관명칭",
    orgId = "116",
    tblId = "DT_MLTM_2086",
    )
df3_2.head(1)

	기관명	기관영문명
0	국토교통부	Ministry of Land, Infrastructure and Transport

수록정보

• 요청변수

요청변수	변수타입	설명	비고
orgId	String	기관코드	필수
tblId	String	통계표ID	필수
detail	String	전체시점 정보 제공	선택

• 출력결과

결과변수	설명
PRD_SE	수록주기
PRD_DE	수록시점

df3_3 = api.get_data(
    "통계표설명",
    "수록정보",
    orgId = "101",
    tblId = "DT_1IN0001",
    # detail = "Y",
    )
df3_3.head(1)

	수록주기	수록기간시작일	수록기간종료일
0	5년	1925	2010

분류/항목

• 요청변수

요청변수	변수타입	설명	비고
orgId	String	기관코드	필수
tblId	String	통계표ID	필수
objId	String	분류코드	선택
itmId	String	분류값코드	선택

• 출력결과

결과변수	설명
OBJ_ID	분류 ID
OBJ_NM	분류 국문명
OBJ_NM_ENG	분류 영문명
ITM_ID	분류값 ID
ITM_NM	분류값 국문명
ITM_NM_ENG	분류값 영문명
UP_ITM_ID	상위 분류값 ID
OBJ_ID_SN	분류값 순번

df3_4 = api.get_data(
    "통계표설명",
    "분류항목",
    orgId = "116",
    tblId = "DT_MLTM_2086",
    )
df3_4.head(1)

	기관ID	통계표ID	코드ID	코드명	분류ID	분류명	분류영문명	분류값ID	분류값명	분류값영문명	분류값순번
0	116	DT_MLTM_2086	14999116.12월기준	12월기준	ITEM	항목	Item code list	13103871014T1	미분양(12월기준)	Unsold Housings	NaN

주석

• 요청변수

요청변수	변수타입	설명	비고
orgId	String	기관코드	필수
tblId	String	통계표ID	필수

• 출력결과

결과변수	설명
CMMT_NM	주석유형
CMMT_DC	주석
OBJ_ID	분류 ID
OBJ_NM	분류 명
ITM_ID	분류값 ID
ITM_NM	분류값 국문명

df3_5 = api.get_data(
    "통계표설명",
    "주석",
    orgId = "116",
    tblId = "DT_MLTM_2086",
    )
df3_5.head(1)

	주석유형	주석
0	통계표	해당연도 12월말 기준

단위

• 요청변수

요청변수	변수타입	설명	비고
orgId	String	기관코드	필수
tblId	String	통계표ID	필수

• 출력결과

결과변수	설명
UNIT_NM	단위 국문명
UNIT_NM_ENG	단위 영문명

df3_6 = api.get_data(
    "통계표설명",
    "단위",
    orgId = "116",
    tblId = "DT_MLTM_2086",
    )
df3_6.head(1)

	단위명	단위영문명
0	호	Apartment Unit

출처

• 요청변수

요청변수	변수타입	설명	비고
orgId	String	기관코드	필수
tblId	String	통계표ID	필수

• 출력결과

결과변수	설명
JOSA_NM	조사명
DEPT_NM	통계표 담당부서
DEPT_PHONE	통계표 담당부서 전화번호

df3_7 = api.get_data(
    "통계표설명",
    "출처",
    orgId = "116",
    tblId = "DT_MLTM_2086",
    )
df3_7.head(1)

	조사명	통계표담당부서	통계표담당부서전화번호
0	「미분양주택현황보고」	국토교통부 주택토지실 주택정책관 주택정책과	044-201-3336

가중치

• 요청변수

요청변수	변수타입	설명	비고
orgId	String	기관코드	필수
tblId	String	통계표ID	필수
분류코드1~분류코드8	String	분류코드1~분류코드8	선택
ITEM	String	항목	선택

• 출력결과

결과변수	설명
C1 ~ C8	분류값 ID1 ~ 분류값 ID8
C1_NM ~ C8_NM	분류값 명1 ~ 분류값 명8
ITM_ID	항목 ID
ITM_NM	항목명
WGT_CO	가중치

df3_8 = api.get_data(
    "통계표설명",
    "가중치",
    orgId = "116",
    tblId = "DT_MLTM_2086",
    )
df3_8

데이터가 존재하지 않습니다.

자료갱신일

• 요청변수

요청변수	변수타입	설명	비고
orgId	String	기관코드	필수
tblId	String	통계표ID	필수
prdSe	String	수록주기	선택 추가정보 (미입력 시 전체주기에 대한 데이터 출력)

• 출력결과

결과변수	설명
ORG_NM	기관명
TBL_NM	통계표명
PRD_SE	수록주기
PRD_DE	수록시점
SEND_DE	자료갱신일

df3_9 = api.get_data(
    "통계표설명",
    "자료갱신일",
    orgId = "116",
    tblId = "DT_MLTM_2086",
    )
df3_9.head(1)

	기관명	통계표명	수록주기	수록시점	자료갱신일
0	국토교통부	미분양현황_종합	년	2001	2022-03-16

통계목록

• 요청변수

요청변수	변수타입	설명	비고
vwCd	String	서비스뷰 코드 · MT_ZTITLE : 국내통계 주제별 · MT_OTITLE : 국내통계 기관별 · MT_GTITLE01 : e-지방지표(주제별) · MT_GTITLE02 : e-지방지표(지역별) · MT_CHOSUN_TITLE : 광복이전통계(1908~1943) · MT_HANKUK_TITLE : 대한민국통계연감 · MT_STOP_TITLE : 작성중지통계 · MT_RTITLE : 국제통계 · MT_BUKHAN : 북한통계 · MT_TM1_TITLE : 대상별통계 · MT_TM2_TITLE : 이슈별통계 · MT_ETITLE : 영문 KOSIS	필수
parentListId	String	시작목록 ID	필수

• 출력결과

결과변수	설명
VW_CD	서비스뷰ID
VW_NM	서비스뷰명
LIST_ID	목록ID
LIST_NM	목록명
ORG_ID	기관코드
TBL_ID	통계표ID
TBL_NM	통계표명
REC_TBL_SE	추천 통계표 여부

df4 = api.get_data(
    "통계목록",
    vwCd = "MT_OTITLE",
    parentListId = "110_20103",
    )
df4.head(1)

	서비스뷰ID	서비스뷰명	기관ID	통계표ID	통계표명	추천통계표여부
0	MT_OTITLE	국내통계 기관별	101	DT_1B040B3	행정구역(시군구)별 주민등록세대수	Y

통계자료

• 요청변수

요청변수	변수타입	설명	비고
apiKey	String	발급된 인증 key	필수
orgId	String	기관 ID	필수
tblId	String	통계표 ID	필수
objL1	String	분류1(첫번째 분류코드)	필수
objL2 ~ objL8	String	분류2(두번째 분류코드) ~ 분류8(여덟째 분류코드)	선택
itmId	String	항목	필수
prdSe	String	수록주기	필수 추가정보
startPrdDe	String	(시점기준) 시작수록시점	선택 시점정보 (시점기준 또는 최신자료기준 택1) ※설정이 없을경우 최근시점1개 조회
endPrdDe	String	(시점기준) 종료수록시점	선택 시점정보 (시점기준 또는 최신자료기준 택1) ※설정이 없을경우 최근시점1개 조회
newEstPrdCnt	String	(최신자료기준) 최근수록시점 개수	선택 시점정보 (시점기준 또는 최신자료기준 택1) ※설정이 없을경우 최근시점1개 조회
prdInterval	String	(최신자료기준) 수록시점 간격 ex) 2019, 2017, 2015 등 2개 시점 간격으로 추출시 [2] 입력	선택 시점정보 (시점기준 또는 최신자료기준 택1) ※설정이 없을경우 최근시점1개 조회

• 출력결과

출력변수	설명	비고
ORG_ID	기관코드
TBL_ID	통계표ID
TBL_NM	통계표명
C1 ~ C8	분류값 ID1 ~ 분류값 ID8	2~8 분류값은 없을 경우 생략
C1_OBJ_NM ~ C8_OBJ_NM	분류명1 ~ 분류명8
C1_OBJ_NM_ENG ~ C8_OBJ_NM_ENG	분류 영문명1 ~ 분류 영문명8
C1_NM ~ C8_NM	분류값 명1 ~ 분류값 명8
C1_NM_ENG ~ C8_NM_ENG	분류값 영문명1 ~ 분류값 영문명8
ITM_ID	항목 ID
ITM_NM	항목명
ITM_NM_ENG	항목영문명
UNIT_ID	단위ID
UNIT_NM	단위명
UNIT_NM_ENG	단위영문명
PRD_SE	수록주기	추가정보
PRD_DE	수록시점
DT	수치값

df5 = api.get_data(
    "통계자료",
    orgId = "116",
    tblId = "DT_MLTM_2086",
    itmId = "ALL",
    objL1 = "ALL",
    objL2 = "ALL",
    prdSe = "Y",
    startPrdDe = "2021",
    endPrdDe = "2021",
    )
df5.head(1)

	기관ID	통계표ID	통계표명	분류명1	분류영문명1	분류값명1	분류값영문명1	분류값ID1	분류명2	분류영문명2	...	분류값영문명2	분류값ID2	항목ID	항목명	항목영문명	단위명	단위영문명	수록주기	수록시점	수치값
0	116	DT_MLTM_2086	미분양현황_종합	대분류	Classification	부문별미분양현황	unsold By sector	13102871014A.0001	구분	Classification	...	Total	13102871014B.0001	13103871014T1	미분양(12월기준)	Unsold Housings	12월기준	Apartment Unit	A	2021	17710

1 rows × 21 columns

참고

• KOSIS 국가통계포털 Open API 가이드
• KOSIS 공유서비스
• PublicDataReader 깃허브 저장소
• PublicDataReader 사용자 모임