공공데이터포털 API 사용법

사이드 프로젝트로 “내 주변 전기차 충전소 찾기” 같은 거 한 번쯤 떠올려보셨죠. 저도 비슷한 거 구상했다가 제일 먼저 벽을 만난 게 데이터였어요. 전국 충전소 데이터를 어디서 구하지? 여기서부터 갑자기 막막해지더라고요.

그때 한 줄기 빛처럼 보였던 게 공공데이터포털이었습니다. 근데 또 문제는, 처음 보는 API 문서랑 낯선 용어들이죠. 저도 처음엔 “이걸 내가 진짜 붙일 수 있나…” 싶어서 삽질 좀 했습니다. 그래도 결국 지도 위에 충전소 위치가 딱 찍히는 순간, 그 쾌감은 아직도 기억나요.

지금 비슷하게 헤매고 계시면, 괜찮습니다. 이 글에서는 제가 겪었던 시행착오를 최대한 줄여드리려고, 공공데이터포털 API를 쓰는 전 과정을 처음부터 끝까지 쉽게 풀어볼게요.

공공데이터포털 API 사용 준비 및 기본

바로 코드부터 치고 싶어도, 여기서는 준비 단계가 꽤 중요합니다. 느낌으로 비유하면 도서관에서 책 빌리려면 회원증 만들고, 책 찾고, 대출 신청하잖아요. 공공데이터포털도 똑같아요. 회원가입하고, 데이터 고르고, 활용 신청하고, 마지막에 열쇠 같은 API 키를 받아야 합니다.

이 단계 대충 넘기면 뒤에서 꼭 한 번 크게 삽질하더라고요. 반대로 여기만 탄탄하게 해두면, 뒤는 생각보다 쭉쭉 갑니다.

공공데이터포털 API 활용 절차는 어떻게 될까요?

전체 흐름은 5단계로 보면 편해요. 순서대로만 따라가면 됩니다. 진짜로요.

1. 회원가입 공공데이터포털은 회원제로 굴러갑니다. 누가 어떤 데이터를 쓰는지 관리도 해야 하고, 트래픽도 통제해야 하니까요. 일반 웹사이트 가입하듯이 정보 넣고 이메일 인증하면 끝나요.
2. 데이터셋 검색 데이터가 진짜 많습니다. 처음엔 저도 원하는 거 찾느라 반나절 날렸어요. 검색창에 키워드 넣고, 데이터 유형을 ‘API’로 필터링하면 좀 살만해집니다. 찾았으면 상세 페이지에서 제공 항목이랑 갱신 주기 정도는 꼭 한 번 보고 가세요.
3. 활용신청 “이거 쓸게요” 하고 신청하는 단계입니다. 활용 목적을 너무 대충 쓰면 승인 지연되는 경우가 있어요. “전국 도서관 위치 정보를 활용한 주변 도서관 추천 웹서비스 개발” 이런 식으로 구체적으로 쓰는 게 보통 잘 통합니다.
4. 승인 및 API 키 발급 신청하면 기관에서 검토하고 승인해줍니다. 저는 보통 하루 안에 메일 받는 편이었는데, 기관마다 2~3일 걸릴 때도 있어요. 승인되면 드디어 인증키(API Key)가 나옵니다. 이제 열쇠 받은 거예요.
5. 개발 및 서비스 연동 발급받은 키로 실제 요청 URL 만들고, 파라미터 붙여서 호출하면 됩니다. 응답 받은 데이터를 앱이나 웹에 뿌려주면 끝이에요. 여기까지 오면 아이디어가 진짜 서비스처럼 보이기 시작합니다.

공공데이터포털 API 키 발급 방법

공공데이터포털 API에서 제일 중요한 게 뭐냐고 물으면, 저는 그냥 API 키라고 말할게요. 이게 있어야 서버가 “아, 이 사람은 승인된 사용자구나” 하고 데이터를 내려줍니다. 그리고 보안도 여기서부터 시작이에요.

API 키는 따로 “키 발급” 메뉴가 있는 게 아니라, 앞에서 말한 활용 절차 중 승인이 떨어지면 자동으로 발급됩니다. 확인은 로그인하고 [마이페이지] > [개발계정 관리]에서 할 수 있어요. 신청한 API 목록이랑 인증키, 일일 트래픽 같은 것도 같이 보입니다.

그리고 보안 얘기 하나만 더 할게요. 제 동료가 예전에 API 키를 깃허브 공개 저장소에 올렸다가, 다음 날 아침에 트래픽이 싹 소진돼서 서비스가 멈춘 적이 있었습니다. 진짜 식은땀 나요. 그래서 API 키는 소스 코드에 박아두지 말고, 환경 변수(Environment Variable)나 별도 설정 파일로 빼서 관리하는 습관을 꼭 들이세요.

API 키 보안 관리 팁

공공데이터포털 API 연동 가이드

키까지 받았으면 이제 진짜 개발 들어가면 됩니다. 공공데이터포털 API는 보통 REST 방식이에요. 어렵게 들리는데, 그냥 “정해진 URL로 요청 보내면 응답이 온다” 이거라고 보시면 됩니다. 우리가 브라우저 주소창에 URL 넣고 페이지 받는 거랑 원리 자체는 비슷해요.

요청 URL은 대충 이런 모양입니다.
"서비스URL?serviceKey=여러분이_발급받은_인증키&파라미터1=값1&파라미터2=값2"Copy

서비스URL은 API 상세설명 페이지에 있는 기본 주소고요.
?는 주소랑 조건을 나누는 구분자입니다.
serviceKey=인증키는 “저 승인받았어요” 증명하는 핵심이고요. 빠지면 거의 100% 에러 납니다.
&는 조건을 여러 개 붙일 때 쓰고요.
기타 파라미터는 필터링용입니다. 예를 들면 pageNo=1, numOfRows=10 이런 애들이요.

요청을 보내면 응답은 XML 또는 JSON으로 옵니다. 응답은 보통 header랑 body로 나뉘는데, 저는 습관처럼 먼저 header의 resultCode가 00인지부터 확인합니다. 이거 안 하면 “데이터가 없는 건가?” “내가 파싱을 잘못했나?” 하면서 한참 헤매요.

공공데이터포털 API 활용 및 문제 해결

기본 연동이 되면 이제부터가 실전이에요. 원하는 데이터만 쏙 뽑아오기도 해야 하고, 호출하다가 터지는 오류도 잡아야 합니다. 여기서 한 번씩 다들 멘붕 오는데, 괜찮아요. 대부분은 패턴이 비슷합니다.

공공데이터포털 API 인증 및 호출

API 호출의 첫 관문은 인증입니다. 요청 URL에 serviceKey=내_인증키Copy만 잘 넣으면 되는데, 이 간단한 데서도 오류가 꽤 나요.

대표적인 인증/호출 오류는 이런 것들이 있습니다.

주요 API 인증 오류 및 해결 방법

참고로 개발 중에 반복 테스트하다 보면, 진짜 본인도 모르게 일일 호출 한도를 다 써버립니다. 특히 화면 새로고침할 때마다 API 때리는 구조로 만들어두면 금방 터져요.

공공데이터포털 API 예제 코드

공공데이터포털이 언어별 예제 코드를 주긴 하는데, 그대로 복붙만 하면 나중에 응용이 안 됩니다. “아, 이게 이런 원리로 호출되는구나” 정도만 잡고 가시면 좋아요.

Python 예제는 보통 requests를 씁니다. URL이랑 파라미터 정리해두고 requests.get() 한 줄이면 호출돼요. 처음 시작이면 파이썬이 제일 덜 무섭긴 합니다.

JavaScript(브라우저) 예제는 fetch()로 호출하는데, 여기서 CORS 때문에 막히는 경우가 많아요. 이건 브라우저 보안 정책이라 자연스러운 거고, 보통은 내 백엔드 서버를 중간에 두고 프록시처럼 호출합니다.

Java 예제는 HttpURLConnectionCopy 같은 걸로 구현하는 경우가 많습니다. 코드가 길어져서 초보 입장에선 좀 빡세긴 한데, 자바 진영에선 흔한 방식이에요.

공공데이터포털 API 데이터는 어떻게 조회할까요?

제가 2023년 여름에 ‘부산시 공영주차장 정보’ API로 주차장 위치 안내 서비스를 만든 적이 있었는데요. 처음엔 “그냥 한 번에 다 가져오면 되겠지” 했다가 응답이 자꾸 끊기더라고요. 알고 보니 한 번에 100건 제한이 있었고요. 그때 페이징의 중요성을 제대로 배웠습니다. 결국 반복문으로 50번 넘게 호출해서 부산시 전체 데이터를 모았어요.

=> 공영주차장 API와 관련된 내용은 해당 링크를 참고하세요!

원하는 데이터를 제대로 조회하려면, 딱 두 가지만 기억하시면 됩니다. 여기서 많이 갈립니다.

1. 파라미터로 필터링하기 API 문서에 조회 조건 파라미터가 있으면 적극적으로 쓰세요. 예를 들어 시도명에 ‘서울특별시’를 넣으면 서울만 받고, 조회일자에 ‘20240520’을 넣으면 그 날짜만 받는 식입니다. 필요 없는 데이터까지 다 받으면 느려지고, 파싱도 귀찮아져요.
2. 페이징(Paging) 처리 대부분 한 번에 가져올 수 있는 데이터 양이 제한돼 있습니다. 그래서 pageNo를 1부터 올려가면서 여러 번 호출해야 해요. 보통은 첫 페이지에서 totalCount를 확인하고, 총 페이지 수 계산해서 루프 돌립니다.

공공데이터포털 API 오류 해결

야심 차게 실행했는데 빨간 오류 뜨면, 그 순간 심장이 철렁하죠. 근데 이건 다들 겪는 코스입니다. 좌절 금지예요. 보통은 아래 케이스 중 하나입니다.

SERVICE_KEY_IS_NOT_REGISTERED_ERROR (미등록 서비스키)
마이페이지에서 URL 인코딩된 인증키를 써보세요. 인증키에 + 같은 특수문자가 있으면, URL로 전달되는 과정에서 깨져서 이런 문제가 나기도 합니다.

INVALID_REQUEST_PARAMETER_ERROR (잘못된 파라미터)
이건 진짜로 한 글자씩 비교해야 할 때가 많습니다. 파라미터 이름 대소문자, 필수값 누락, 날짜 형식 같은 거요. 꿀팁 하나 드리면, Postman에서 먼저 성공시키세요. 거기서 성공하면 API는 멀쩡한 거고, 문제는 내 코드 쪽일 확률이 큽니다.

SYSTEM_ERROR 등 서버 문제
가끔은 내 잘못이 아닙니다. 저도 SYSTEM_ERROR 뜨면 제 코드가 문제인 줄 알고 몇 시간 날린 적 있어요. 알고 보니 서버 점검 중이더라고요. 이런 건 잠깐 기다렸다가 다시 해보고, 공공데이터포털 공지사항도 같이 확인해보시면 좋습니다.

공공기관 데이터를 이렇게 쉽게 끌어다 쓸 수 있다는 건 개발자 입장에선 꽤 큰 무기예요. 처음엔 낯설고 문서도 불친절하게 느껴질 수 있는데, 한 번만 연결해보면 그 다음부터는 속도가 확 붙습니다. 오늘 내용대로 한 번 붙여보시고, 막히는 지점 있으면 거기서부터 같이 삽질 줄여보죠.

FAQ