공공데이터포털 API 발급

공공데이터포털에는 수만 건의 데이터가 공개되어 있습니다. 그런데 막상 프로그램에서 가져다 쓰려고 하면 첫 관문에서 막히는 경우가 많습니다. 인증키를 어디서 받는지, 왜 두 종류인지, 신청했는데 왜 바로 안 되는지가 한 번에 정리되어 있지 않기 때문입니다.

이 글은 회원가입부터 첫 호출이 성공할 때까지의 과정을 순서대로 정리한 것입니다. 처음 만나게 되는 오류와 그 원인도 함께 다룹니다.

전체 흐름

먼저 큰 그림을 잡고 시작하는 편이 좋습니다.

1. 공공데이터포털 회원가입
2. 필요한 데이터 검색
3. 해당 데이터에 활용신청
4. 인증키 확인 후 호출

여기서 가장 많이 오해하는 부분은 인증키를 따로 신청하는 절차가 없다는 점입니다. 특정 데이터에 활용신청을 하면 그 과정에서 인증키가 발급됩니다. 계정당 하나의 인증키를 받고, 그 키로 활용신청이 승인된 모든 API를 호출하는 구조입니다.

1단계. 데이터 찾기 — 오픈API인지 확인

공공데이터포털에서 데이터를 검색하면 결과가 여러 유형으로 나뉩니다. 이 구분을 놓치면 엉뚱한 것을 신청하게 됩니다.

유형	성격
오픈 API	실시간 호출로 데이터를 받아오는 방식. 인증키가 필요합니다.
파일 데이터	CSV, XLSX 등을 직접 내려받는 방식. 인증키가 없어도 됩니다.
표준 데이터셋	여러 기관의 같은 종류 데이터를 통일된 항목으로 정리한 것

주기적으로 갱신되는 정보를 계속 받아와야 한다면 오픈 API를, 한 번만 받아서 분석할 것이라면 파일 데이터를 고르면 됩니다. 파일 데이터가 훨씬 간단하므로, 목적이 일회성 분석이라면 굳이 API를 쓸 이유가 없습니다.

2단계. 활용신청

원하는 오픈 API 상세 페이지에서 우측 상단의 활용신청 버튼을 누르면 신청 화면으로 넘어갑니다. 입력할 항목은 다음과 같습니다.

• 활용 목적 — 웹사이트 개발, 앱 개발, 참고자료, 연구 등에서 선택합니다.
• 상세기능 선택 — 하나의 API 안에 여러 기능이 있는 경우가 많습니다. 필요한 기능에 모두 체크해야 합니다. 여기서 빠뜨리면 그 기능만 호출이 실패합니다.
• 라이선스 표시 동의 — 출처 표시 조건 등을 확인하고 동의합니다.

신청 후 승인은 두 가지로 나뉩니다.

구분	처리
자동승인	신청 즉시 승인되며 바로 인증키가 발급됩니다.
심의승인	제공 기관의 검토를 거칩니다. 기관에 따라 며칠이 걸릴 수 있습니다.

대부분의 생활 정보 데이터는 자동승인입니다. 심의승인 대상이라면 상세 페이지에 표시되어 있으므로 신청 전에 확인할 수 있습니다.

3단계. 인증키 확인

발급된 인증키는 마이페이지 → 데이터 활용 → 오픈API → 인증키 발급현황에서 확인합니다. 개별 API의 상세 페이지에서도 볼 수 있습니다.

여기서 키가 두 개로 보이는 경우가 있습니다.

• 일반 인증키(Encoding) — URL 인코딩이 적용된 형태입니다. %2B, %3D 같은 문자가 섞여 있습니다.
• 일반 인증키(Decoding) — 인코딩되지 않은 원본 형태입니다. +, = 가 그대로 보입니다.

둘은 같은 키를 다르게 표기한 것입니다. 문제는 API마다 어느 쪽을 받아들이는지가 다르다는 점입니다. 브라우저 주소창에 직접 붙여 넣을 때는 Encoding 키가, 프로그램에서 파라미터로 넘길 때는 Decoding 키가 맞는 경우가 많습니다. 다만 예외가 있으므로, 인증 오류가 나면 다른 쪽 키로 한 번 더 시도해 보는 것이 가장 빠른 확인 방법입니다.

4단계. 첫 호출

요청 주소는 API 상세 페이지의 기술문서에 나와 있습니다. 대체로 다음 형태를 따릅니다.

http://apis.data.go.kr/기관코드/서비스명/오퍼레이션명?serviceKey=인증키&numOfRows=10&pageNo=1&_type=json

공통적으로 자주 쓰이는 파라미터는 다음과 같습니다.

파라미터	역할
serviceKey	인증키. 필수입니다.
numOfRows	한 번에 받아올 건수
pageNo	페이지 번호. 전체를 받으려면 이 값을 늘려가며 반복합니다.
_type	응답 형식. 지정하지 않으면 XML로 오는 경우가 많습니다.

처음에는 numOfRows를 10 정도로 작게 두고 응답 구조부터 확인하는 편이 좋습니다. 항목 이름이 기술문서와 다른 경우가 종종 있어서, 실제 응답을 눈으로 보고 맞추는 과정이 필요합니다.

처음 만나는 오류들

첫 호출에서 자주 마주치는 응답과 원인입니다.

• SERVICE_KEY_IS_NOT_REGISTERED_ERROR — 등록되지 않은 키라는 뜻이지만, 실제로는 발급 직후 반영 대기 중인 경우가 대부분입니다. 시스템 반영에 시간이 걸리므로 한 시간 정도 뒤에 다시 시도해 보시기 바랍니다. 그래도 같다면 Encoding과 Decoding 키를 바꿔서 시도합니다.
• NO_OPENAPI_SERVICE_ERROR — 요청 주소가 틀렸거나, 활용신청 시 해당 상세기능에 체크하지 않은 경우입니다. 신청 내역에서 기능 목록을 다시 확인합니다.
• LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR — 일일 호출 한도를 넘겼습니다. 개발 단계 계정은 한도가 낮게 설정되어 있으며, 운영계정으로 전환을 신청하면 상향됩니다.
• 응답은 오는데 데이터가 비어 있음 — 필수 파라미터가 빠졌거나 조회 조건에 맞는 데이터가 없는 경우입니다. 기술문서의 필수 항목을 다시 확인합니다.

활용 기간과 한도

활용신청에는 기간이 있습니다. 기간이 만료되면 호출이 중단되므로, 계속 사용할 예정이라면 만료 전에 연장을 신청해야 합니다. 마이페이지의 활용 현황에서 남은 기간을 확인할 수 있습니다.

일일 호출 한도 역시 API마다 다르게 설정되어 있습니다. 개발 단계에서는 제한이 있고, 서비스에 실제로 적용할 계획이라면 운영계정 전환을 신청하는 것이 일반적입니다. 전환 시 활용 사례를 함께 제출하게 됩니다.

자주 묻는 질문

Q. 인증키는 API마다 따로 받아야 하나요?
아닙니다. 계정당 하나의 인증키가 발급되며, 활용신청이 승인된 모든 API를 같은 키로 호출합니다. 다만 신청하지 않은 API는 같은 키로도 호출되지 않습니다.

Q. Encoding 키와 Decoding 키 중 어느 것을 써야 하나요?
API마다 다릅니다. 브라우저에서 주소를 직접 입력할 때는 Encoding, 코드에서 파라미터로 전달할 때는 Decoding이 맞는 경우가 많지만 예외가 있습니다. 인증 오류가 나면 다른 쪽으로 바꿔 시도하는 것이 가장 확실합니다.

Q. 신청 직후 바로 호출했는데 인증 오류가 납니다.
발급된 키가 시스템에 반영되기까지 시간이 걸립니다. 한 시간 정도 기다린 뒤 다시 시도해 보시기 바랍니다. 이 경우가 초보 단계에서 가장 흔한 실패 원인입니다.

---

자료 출처 · 공공데이터포털 공공데이터 이용가이드
포털 화면 구성과 정책은 변경될 수 있으므로, 실제 신청 시에는 공공데이터포털의 최신 안내를 함께 확인하시기 바랍니다.