공공데이터 포털에서 Open API 사용 방법

개발고생일지/API

공공데이터 포털에서 Open API 사용 방법

Fartist 2023. 3. 10. 12:07

- 목차
들어가는 말
1. 공공데이터 포털 회원가입
2. 공공데이터 포털 Open API 인증키 신청하기
3. 공공데이터 포털 Open API 사용 방법
4. 실습
갈무리

[그림 1] 공공데이터 포털에서 OpenAPI 사용 방법 — [그림 1] 공공데이터 포털에서  OpenAPI 사용 방법

들어가는 말

현재 파이썬으로 웹 크롤링을 하는 것을 공부하면서 교재의 내용과 상이한 부분이 있어서 그 부분을 이렇게 기록으로 남깁니다. 구글에서 공공데이터 포털 사용법에 대해서 검색해 보면 교재와 동일한 예시 그림을 제공하고 있었습니다. 현재의 공공데이터 포털은 새로운 형식으로 Open API를 사용하도록 개선된 것으로 보입니다. 새로운 사용법을 익히는데 개인적으로 굉장히 힘들었어서, 이 글이 다른 분들에게 도움이 되기를 바랍니다. 교재는 '도서출판인사이트'의 교재명 '웹 크롤링 & 데이터 분석 with 파이썬'입니다. 해당 서적을 통해서 파이썬과 웹 크롤링 기술을 처음 접하는 분들에게도 이 글이 도움이 되기를 기원합니다. 또한 교재 없이 공공데이터 포털을 처음 사용하고자 하시는 분들에게는 회원가입 절차부터 다루므로, 천천히 글을 따라 진행하시면 공공데이터 포털에서 Open API를 사용하는데 도움이 될 것입니다.

1. 공공데이터 포털 회원가입

아래의 링크는 공공데이터 포털 홈페이지 주소입니다. 링크를 클릭하거나 검색창에 '공공데이터 포털'을 검색하면 [그림 2]처럼 메인 화면에 접속할 수 있습니다.

우상단의 '회원가입'을 누르면 회원가입 페이지로 이동합니다.

본인의 실명과 이메일 주소를 입력하고 '가입확인'을 합니다.

'일반회원'을 선택하면 아래에 연령선택이 나타납니다. '14세 이상 일반인'을 선택하면 가입하기 창으로 넘어갑니다.

개인정보를 입력하고 [그림 6]의 약관 동의를 하면 회원가입 절차는 끝납니다.

2. 공공데이터 포털 Open API 인증키 신청하기

메인 화면의 검색창에서 '한국부동산원 부동산 거래 현황 통계 조회 서비스'를 검색합니다.

여러 검색 내역중 [오픈 API]를 클릭하여 Open API 중에서 검색한 이름과 같은 API를 찾습니다. Open API를 이용하기 위해서는 인증키를 발급받아야 합니다 [그림 8] 우측 하단에 있는 '활용신청'을 클릭합니다.

활용목적과 내용을 적당히 작성하고 마지막 '라이선스 표시'에서 이용허락범위란에 '동의 체크'를 하고 활용신청을 합니다. 보통 빠르면 바로 인증키를 발급받기도 하고, 1시간에서 3시간가량 인증키 발급이 걸릴 수 있습니다. 혹시 이후에도 인증키 발급에 어려움이 있다면 Q&A 질문하기로 해당 문제를 해결하셔야 합니다.

[마이페이지] > [인증키 발급현황]을 살펴보면 발급받은 인증키를 확인할 수 있습니다. 오른쪽 하단에는 '일반 인증키 재발급' 버튼이 있습니다. 공공데이터 포털에서는 특별한 상황이 아니면 인증키 재발급 행위를 자제할 것을 권고합니다. 재발급에 관해서는 사전에 포털 측에 문의 후 진행하시는 것을 권장드립니다.

[마이페이지] > [개발계정]으로 들어가면 활용신청 내역을 볼 수 있습니다. 글쓴이는 이미 신청하여 인증키를 발급받았으므로 '활용 1건'으로 등록되어 있습니다.

3. 공공데이터 포털 Open API 사용 방법

지금부터 본격적으로 Open API를 사용하는 방법에 대해서 알아보겠습니다. [그림 11]에서 활용신청한 '한국부동산원_부동산 거래 현환 통계 조회 서비스'를 클릭합니다.

활용신청한 서비스내역을 확인할 수 있습니다. 하단을 보면 일반 인증키가 두 가지(Encoding, Decoding)이 있습니다. 위에 밑줄을 보면 API마다 구동되는 인증키가 다를 수 있으므로 두 가지 인증키를 모두 시도하여 사용가능한 인증키를 찾아 사용할 것을 권하고 있습니다. [그림 13]은 인증키를 사용하는 곳을 설명하고 있습니다.

1) Open API 명세 확인 가이드

1번 'Open API 명세 확인 가이드'를 클릭하면 [그림 14]가 나타납니다. 명세 확인 가이드는 쉽게 말하면 이 Open API를 활용할 때 사용자가 반드시 알아야 할 정보를 순차적으로 알려주는 가이드 북입니다. 처음 API를 접하는 분들에게는 바로바로 이해가 되지 않을 수 있습니다. 하지만 제공된 Open API를 사용하기 위한 파라미터나 인증키 설정 절차 등은 꼼꼼히 읽어봐야 하는 항목이므로 반드시 숙지하셔야 합니다.

2) 인증키 설정

2번 '인증키 설정'을 누르면 [그림 15]와 같은 창이 나타납니다.

글쓴이는 일반 인증키(Decoding)을 복사하여 ApiKeyAuth2 (apiKey)에 넣고 '설정' 버튼을 클릭하였습니다. 이어서 '닫기'를 누르면 인증키의 설정이 끝납니다. 이 과정은 앞선 설명한 것처럼 API 마다 가동하는 인증키 설정이 다를 수 있으므로 직접 Encoding과 Decoding을 시도해봐야 합니다. 글쓴이가 API에 사용하는 건 'serviceKey'이므로 ApiKeyAuth2 (apiKey)에서만 테스트합니다.

3) 요청변수

인증키 설정이 끝나면 이제 [그림 13]의 '요청변수'내용을 확인합니다. 요청변수는 API에서 데이터를 조회해서 받기 위해 사용자가 직접 입력해야 하는 입력란에 대한 설명입니다. 요청변수 빨간 박스 안의 최하단부를 살펴보면 괄호() 안에 간략한 사용예시가 제시되어 있습니다. 가령 본인이 원하는 데이터의 적용기간이 2021년 1월부터 2021년 12월까지 라면 GTE 요청변수란에 '202101'을 입력하고 LTE 요청변수란에 '202112'를 입력하면 됩니다. 만약 1월과 12월이 포함되지 않은 데이터를 원한다면 '202101'을 GTE 대신 GT에 입력하고, '202112'를 LTE 대신 LT에 입력하면 됩니다. (2021년 1월 < 조사기간 < 2021년 12월) 요청변수에 대한 설명은 활용신청을 하는 Open API마다 다르기 때문에, 다른 Open API를 사용할 때마다 이 요청변수 설명란을 유심히 살펴보시기 바랍니다.

각각의 약자 유래
EQ = EQual (똑같은)
LT = LiTtle (더 작은) 또는 Little Than (~보다 더 작은)
LTE = LT + Equal
GT = GreaTer (더 큰) 또는 Greater Than (~보다 더 큰)
GTE = GT + Equal

4) API

[그림 13]의 최하단을 보면 사용할 수 있는 API의 종류를 제시하고 있습니다. 여러 API 중에서 '부동산 거래 건수 조회'API를 사용해 보겠습니다.

1) Page (페이지 쪽수)

첫 번째 'Page' 입력창은 'page index'를 입력하는 곳입니다. 번역하면 한국어로 '쪽수'라고 할 수 있겠습니다. 이 page index는 다음에 나오는 'page size'와 연계해서 생각해야 합니다.

2) perPage (페이지 크기)

두 번째 'perPage'는 'page size'를 정하는 것입니다. 한 페이지에 몇 개의 데이터를 보여줄 것인지 정할 수 있습니다. 이제 'page index'와 함께 'page size'에 대해서 생각해 봅시다.

2020년 1월부터 2021년 12월까지의 거래 건수 데이터 = 24개의 데이터

우리가 24개의 데이터(2020년 1월부터 2021년 12월까지)를 원한다고 예를 들어보겠습니다.

page index = 1, page size = 10
결과 : 매칭된 24개의 데이터 중, 임의의 10개의 데이터가 담긴 한 장의 페이지를 받아 볼 수 있음

디폴트값인 page index = 1, page size = 10 인 상태에서는 '한 페이지에 10개의 데이터만 담을 수 있는 종이 한 장을 호출'한다는 뜻이 됩니다. 그럼 우리는 2020년 1월부터 2021년 12월까지 24개의 데이터 중에서 임의의 10개의 데이터만 담은 1 페이지의 데이터만 받을 수 있습니다. 만약 한 페이지에 24개의 데이터를 모두 담은 것을 받고 싶다면 page size를 24개 이상으로 설정하면 됩니다.

page index = 1, page size = 30
결과 : 24개의 매칭된 데이터가 담긴 한 장의 페이지를 받아 볼 수 있음

page index = 1, page size = 30으로 요청변수를 설정하면 우리가 원하는 24개의 데이터를 한 장의 페이지에 담아 받아 볼 수 있습니다.

그렇다면 다음과 같은 설정은 어떨까요? page index = 4 인 요청변수로는 4장짜리 데이터를 받아 볼 수 있을까요?

page index = 4, page size = 10
결과 : 아무 데이터가 없음

결과는 아무런 데이터가 담겨있지 않은 빈 페이지를 받아 볼 수 있습니다. page index는 '쪽수'라는 것을 명심해야 합니다. 위의 예시와 같은 요청변수를 설정하여 데이터를 호출하면 4장의 데이터 페이지를 모두 받는 것이 아니라 4쪽 한 장을 받아 볼 수 있습니다. 게다가 우리가 원하는 데이터의 개수는 총 24개입니다. 한 장에 10개의 데이터를 담는 페이지가 4장이 있다면 1 ~ 2 page에는 10개의 데이터, 3 page에는 4개의 데이터만 있고 4 page에는 아무 데이터도 없는 빈 페이지가 됩니다. 이때 우리가 'page index = 4'로 설정하면 4쪽 페이지만 호출하므로 빈 데이터 페이지를 열람하게 됩니다.

만약 모든 데이터를 한 번에 호출하여 받아보고 싶다면 다음과 같은 조건으로 page index와 page size를 설정해야 합니다.

page index = 1, page size = 원하는 데이터의 개수 이상
결과: 매칭 데이터 24개를 모두 담은 한 장의 페이지를 받아 볼 수 있음

3) returnType (반환 타입)

'returnType'은 호출할 데이터 양식을 정할 수 있습니다. 디폴트 값은 json형식을 따르는 데이터 양식입니다. 만약 xml형식을 따르는 데이터 양식으로 받아보고 싶다면 이 칸에 'xml'을 입력하면 됩니다.

4) 조건식

'cond[::]'는 '조건식[::]'을 뜻합니다. cond는 Condition(조건)의 약자입니다. [::]는 '::'을 기준으로 앞에는 조건식의 이름, 뒤에는 사용된 부등호가 영문으로 표기되어 있습니다. [그림 17]의 위에서부터 차례대로 각각의 조건식은 다음과 같습니다.

cond[RESEARCH_DATE::LT] = 조건식[조사기간::<]
cond[RESEARCH_DATE::LTE] = 조건식[조사기간::≤]
cond[RESEARCH_DATE::GT] = 조건식[조사기간::>]
cond[RESEARCH_DATE::GTE] = 조건식[조사기간::≥]
cond[REGION_CD::EQ] = 조건식[지역코드::=]
cond[DEAL_OBJ::EQ] = 조건식[지역코드::=]

만약 조사하고자 하는 기간이 2020년 1월부터 2021년 12월까지 라면 다음과 같이 입력하면 됩니다.

cond[RESEARCH_DATE::LT] =
cond[RESEARCH_DATE::LTE] = 202112
cond[RESEARCH_DATE::GT] =
cond[RESEARCH_DATE::GTE] = 202001
cond[REGION_CD::EQ] =
cond[DEAL_OBJ::EQ] =

5) 지역코드

지역코드는 각 Open API 마다 제공되는 별도의 기술문서에 기재되어 있습니다. 기술문서를 열람하기 위해서는 [그림 18]의 빨간 박스의 URL을 주소창에 복사하여 이동합니다.

기술문서는 워드 파일로 작성되어 있으며, 워드 프로그램이 없다면 열람은 구글Docs에서 할 수 있습니다.

6) 거래유형

[그림 17]의 마지막 요청변수 '거래유형'은 부동산 거래품목을 유형별로 나눈 코드입니다. 코드의 개수가 적어 기술문서의 열람 없이 바로 사용할 수 있도록 기재되어 있습니다.

[그림 20]은 API를 호출했을 때 결과창에 나오는 코드에 대한 설명입니다. 각각 '200', '401', '500'으로 결괏값에 대한 코드가 지정되어 있고 그 뜻을 표시하고 있습니다.

4. 실습

2020년 1월~ 2021년 12월까지 24개월의 데이터
서울 전체 지역에서
아파트 거래 건수 조회
json 타입으로 호출

우리가 실습해 볼 요청변수의 값은 위와 같습니다. 이 값을 API 요청변수란에 입력하기 위해서는 하나의 과정이 필요합니다.

[그림 21]의 빨간 박스 'Open API 실행 준비'를 클릭해 봅시다. 그러면 요청변수란이 값을 입력할 수 있도록 활성화됩니다.

각 요청변수란에 입력할 값은 다음과 같습니다.

page = 1
perPage = 30
returnTye = 빈칸(default : json)
LTE = 202112
GTE = 202001
지역코드 = 11000
거래유형 = 05

모든 값을 입력하고 [그림 22]의 'OpenAPI 호출' 버튼을 클릭합니다.

[그림 23]은 호출 결과 나타나는 영역입니다.

1) Request URL

데이터를 받아올 때 사용하는 URL입니다. 사용하고 있는 코드에서 해당 URL을 입력하여 호출한 Open API의 데이터에 접근할 수 있습니다.

2) Server response Code

Open API를 호출하여 돌려받은 결과입니다. 코드를 보시면 '401'입니다. 401은 [그림 20]에서 '인증 정보가 정확하지 않음을 뜻하는 코드라는 걸 배웠습니다. 무언가 문제가 있는 것입니다. 2번 빨간 박스의 'Detail'란을 보면 "인증키는 필수 항목입니다."라고 말합니다. 이것은 우리가 설정한 인증키가 잘못되었거나, 오랜 시간 페이지를 사용하지 않아 자동 로그아웃이 되어 인증키 설정이 풀린 탓입니다. [그림 13, 15]를 참고하여 다시 인증키 설정을 해 줍니다.

'Request URL'을 보면 'serviceKey='가 추가된 것을 확인할 수 있습니다.

'Server response Code'를 보면 호출된 데이터 값이 나열된 것을 볼 수 있습니다. 각 항목별 뜻은 다음과 같습니다.

ALL_CNT = all count = 거래 건수
DEAL_OBJ = deal object = 거래유형
LEVEL_NO = level number = 지역구분 레벨
REGION_CD = region code = 지역코드
REGION_NM = region name = 지역이름
RESEARCH_DATE = research date = 조사기간

각 항목은 Open API를 호출할 때 기입하는 요청변수에 따라 달라질 수 있습니다. 방금 언급한 항목별 뜻을 포함해서 달라지는 각 항목의 뜻은 [그림 19]에서 언급한 '기술문서'에서 확인할 수 있습니다.

마지막까지 스크롤을 내려보면 검색 결과 요약이 있습니다.

matchCount = 매칭된 데이터 24개
page = 페이지 쪽수 1
perPage = 페이지에 담기는 총데이터의 개수 30개
totalCount = Open API에서 가지고 있는 총 데이터의 개수 411,531개

application/json = 반환타입 json
charset=UTF-8 = 문자 인코딩 방식 = UTF-8

갈무리

지금까지 공공데이터 포털에서 회원가입 후 Open API에 활용신청을 하고 사용하는 방법에 대해서 알아보았습니다. 다른 API는 저마다 다른 요청변수와 명세 확인 가이드, 기술문서가 있습니다. 여기서 언급한 예시를 가지고 적용한다면 무리 없이 적응할 수 있을 것입니다. 또한 '웹크롤링 & 데이터 분석 with 파이썬' 책으로 학습하고 있는 분들에게는 책의 내용과 다른 바뀐 내용에 대해서 학습을 이어가는데 도움이 되었으면 합니다. 이상으로 글을 마칩니다.

저작자표시 비영리 변경금지

현재글공공데이터 포털에서 Open API 사용 방법

생활 정보와 취미 생활, 개발 공부, 앱 서비스에 관련된 ‘개고생 일지(Diary)’입니다.

.zshrc, 3.5파이, action, Adobe, AhnLab, Apple, CCL, columns, Command not found, concat, convertio, dataframe, delfino, DIY, DP, drop, empty, gif, HDMI, HTTP ERROR 400,

Today :
Yesterday :

개고생일지_아닐지