[마이 프로젝트] 공공데이터 API 신청부터 첫 화면까지

신청하고 나서도 바로 되지는 않습니다.

한 줄 요약: 공공데이터포털에서 활용 신청을 하고 받은 키로 첫 데이터를 블로그 화면에 띄우기까지, 막혔던 지점은 키 반영 시간, 키 두 종류, 주소 속 특수문자 세 가지였습니다. 순서대로 적습니다.

신청은 생각보다 간단했습니다

개발을 배운 적 없는 상태로 시작했습니다. 공공데이터포털에서 쓰고 싶은 데이터를 찾아 활용신청을 누르면 됩니다. 신청 화면에는 사용 목적을 적는 칸이 있는데, 개인 블로그에 정보를 정리해서 보여주려 한다고 있는 그대로 적었습니다.

여기서 길이 갈립니다. 신청하면 바로 승인되는 데이터가 있고, 담당자 확인을 거쳐야 하는 데이터가 있습니다. 제가 쓴 목록 API는 즉시 승인이었고, 신청하자마자 키가 나왔습니다. 승인 방식은 데이터마다 다릅니다.

공공데이터포털 안내 페이지는 누구나 포털에서 제공하는 공공데이터를 내려받거나 오픈 API 활용신청을 통해 제약 없이 활용할 수 있다고 설명합니다. 목록에서 데이터를 찾을 때는 데이터 명칭, 키워드, 설명을 넣어 검색하라고 안내합니다. 이름만 보지 말고 설명까지 읽고 고르세요.

주소 하나를 만드는 것이 전부입니다.

신청 전에 아래 네 가지를 먼저 정리해 두면 이후 단계가 훨씬 덜 막힙니다.

• 어떤 데이터가 필요한지, 그 데이터가 포털 목록에 있는지
• 사용 목적을 어떻게 적을지(저는 개인 블로그에 정보를 정리해 보여준다고 그대로 적었습니다)
• 응답을 어떤 형식으로 받을지(제 코드는 returnType=JSON으로 지정했습니다)
• 받은 키를 어디에 보관할지

키를 받고도 바로 안 됐습니다

여기서 첫 번째로 막혔습니다. 키를 받자마자 호출하면 실패했습니다. 승인은 됐는데 서버에 반영되기까지 시간이 걸리는 것으로 보였고, 제 경우에는 한 시간쯤 지난 뒤에 호출이 됐습니다.

이때 가장 흔한 실수는 주소나 코드를 계속 고치는 것입니다. 키가 막 나온 직후라면 코드가 아니라 시간이 문제일 수 있습니다. 코드를 바꾸기 전에 한 시간 정도 기다린 뒤 같은 주소를 다시 불러 보세요. 같은 주소로 결과가 달라진다면 반영 시간 문제였다는 증거가 됩니다.

한 시간은 제 경우의 값일 뿐이니 기준으로 삼지 마시고, 안 되면 시간을 두고 다시 시도한다는 순서만 기억하세요.

기다리는 동안 할 수 있는 일도 많습니다. 아래 목록은 키가 반영되기를 기다리는 시간에 미리 해 둘 수 있는 것입니다.

• 요청 주소의 구조를 위 순서대로 조립해 둡니다.
• 응답을 통째로 화면에 찍어 보는 코드를 먼저 만들어 둡니다.
• 키가 두 종류라면 어느 쪽을 먼저 넣어 볼지 정해 둡니다.
• 방문자에게 데이터를 어떻게 보여 줄지 화면 구성을 잡아 둡니다.

이렇게 해 두면 호출이 처음 성공하는 순간 바로 화면까지 이어 볼 수 있습니다.

키가 두 종류입니다

두 번째로 막힌 지점은 키가 두 종류라는 점이었습니다. 인코딩된 키와 디코딩된 키가 따로 나옵니다. 어느 쪽을 써야 하는지 화면에 적혀 있지 않아서, 둘 다 넣어 보고 되는 쪽을 골랐습니다.

왜 이런 일이 생기는지는 아래 주소 만들기에서 설명하는 인코딩과 연결됩니다. 키 안에 주소에서 특별한 뜻을 갖는 문자가 들어 있으면 그대로 붙였을 때 주소가 깨집니다. 그래서 이미 변환된 형태의 키와 원래 형태의 키를 함께 주는 것입니다.

고르는 방법은 간단합니다. 주소에 키를 직접 붙이는 코드라면 변환 함수를 한 번 씌워서 쓰고, 이미 변환된 키를 쓴다면 변환을 중복해서 씌우지 않습니다. 이미 변환된 문자열에 다시 변환을 걸면 퍼센트 기호(%)까지 바뀌기 때문입니다. MDN 문서가 밝히는 변환 제외 문자 목록에 퍼센트 기호가 들어 있지 않다는 점에서 알 수 있습니다. 어느 쪽이 맞는지는 API마다 달라서, 저는 직접 넣어 보고 정했습니다.

시험하는 순서를 정리하면 아래와 같습니다. 한 번에 하나씩만 바꾸는 것이 요령입니다.

1. 인코딩된 키 하나를 넣고 호출합니다.
2. 인증 오류가 나면 다른 종류의 키로 바꿔 다시 호출합니다.
3. 된 쪽 키와 그때 변환 함수를 썼는지 안 썼는지를 함께 적어 둡니다.

세 번째가 의외로 중요합니다. 나중에 코드를 고칠 때 어느 키를 어떤 방식으로 넣었는지 잊으면 같은 문제를 다시 겪게 됩니다.

요청 주소를 만드는 방법

공공데이터 API를 쓴다는 것은 결국 주소 하나를 만들어 부르는 일입니다. 기본 주소 뒤에 조건을 물음표와 앰퍼샌드로 이어 붙입니다. 제가 쓴 코드는 아래와 같습니다.

var url = API_BASE + '/serviceList'
        + '?page=' + page               // 몇 번째 묶음인지
        + '&perPage=' + PER_PAGE        // 한 번에 몇 개
        + '&returnType=JSON'            // 어떤 형식으로 받을지
        + '&serviceKey=' + encodeURIComponent(KEY);

마지막 줄의 encodeURIComponent에는 이유가 있습니다. 키 안에 특수문자가 들어 있으면 주소가 깨지기 때문입니다. 저는 이 사실을 몰라 한참 헤맸습니다. 키를 그대로 붙였더니 계속 인증 오류가 났습니다.

MDN 문서는 이 함수가 영문 대소문자, 숫자, 그리고 - _ . ! ~ * ' ( )를 제외한 모든 문자를 변환한다고 설명합니다. 주소에서 구분 역할을 하는 & = ? / : # + ;도 모두 변환 대상입니다. 값 하나가 주소의 구조를 흔들지 않게 하려고 쓰는 함수입니다.

셋 다 문서에는 잘 안 적혀 있습니다.

문자	주소에서 맡는 역할	값 안에 있으면 생기는 일	변환 결과
&	조건과 조건 사이를 가르는 문자	서버가 새 조건의 시작으로 읽을 수 있습니다.	%26
?	조건이 시작되는 자리를 알리는 문자	주소 구조가 흔들립니다.	%3F
공백	주소에 그대로 넣기 어려운 문자	변환하지 않으면 값이 그대로 전달되지 않을 수 있습니다.	%20

위 표의 변환 결과는 MDN 문서의 예시에서 그대로 가져온 값입니다. 문서에 나온 예는 Jack & Jill?이 Jack%20%26%20Jill%3F로 바뀌는 것입니다.

응답이 비었을 때 보는 순서

주소는 맞는 것 같은데 데이터가 오지 않을 때가 있습니다. 제가 쓰는 순서는 다음과 같습니다.

1. 브라우저 주소창에 그 주소를 그대로 넣어 봅니다. 여기서 데이터가 보이면 코드 문제이고, 안 보이면 주소나 키 문제입니다.
2. 응답을 통째로 찍어 봅니다. 데이터 대신 오류 메시지가 들어 있는 경우가 많습니다.
3. 필드 이름을 확인합니다. 문서에는 items라고 되어 있는데 실제로는 data로 오는 경우를 봤습니다.

아래 표는 이 순서에 제가 겪은 증상을 붙여 정리한 것입니다.

증상	의심할 원인	먼저 해 볼 일
키를 받은 직후 호출이 실패	서버에 키가 아직 반영되지 않음	시간을 두고 같은 주소를 다시 호출
계속 인증 오류	키 속 특수문자가 주소를 깨뜨림	키 부분에 변환 함수를 쓰거나, 다른 종류의 키로 교체
오류 없이 데이터가 비어 있음	주소 또는 조건 문제	같은 주소를 주소창에 넣어 결과를 직접 확인
화면에 아무것도 안 그려짐	필드 이름이 문서와 다름	응답 전체를 찍어 실제 필드 이름 확인

응답 상태 번호를 읽을 수 있다면 판단이 더 쉬워집니다. MDN의 상태 코드 설명에 따르면 401은 인증이 안 된 요청, 403은 서버가 신원은 알지만 접근 권한이 없는 요청, 404는 요청한 자원을 찾지 못한 경우, 429는 짧은 시간에 요청을 너무 많이 보낸 경우, 500은 서버 내부 오류입니다. 번호만 보아도 키 문제인지 주소 문제인지 횟수 문제인지 구분할 수 있습니다.

목록에 없는 데이터가 필요할 때

쓰고 싶은 데이터가 포털 목록에 없을 때는 제공신청이라는 별도 절차가 있습니다. 공공데이터포털 안내에 따르면 해당 기관은 신청을 받은 날부터 10일 이내에 제공 여부를 정해 신청인에게 알립니다. 제공하지 않기로 했다면 그 이유를 알려 주고, 그 결정에 이의가 있으면 처분을 받은 날부터 60일 이내에 분쟁조정을 신청할 수 있습니다.

저는 이 절차를 쓰지 않았습니다. 제가 필요한 목록은 이미 포털에 있었기 때문입니다. 다만 데이터를 찾다가 막혔을 때 이런 길이 있다는 것은 알아 두면 좋습니다. 개인정보나 영업비밀, 제3자의 저작권이 포함된 데이터는 제공 대상에서 제외된다는 점도 같은 안내에 적혀 있습니다.

정리하면 순서는 이렇습니다. 목록에서 검색하고, 있으면 활용신청을 하고, 없으면 제공신청을 합니다. 활용신청에서도 승인이 즉시인지 담당자 확인이 필요한지는 데이터마다 다릅니다.

상황	쓰는 절차	걸리는 기간(안내 기준)
목록에 있는 데이터를 쓰고 싶다	활용신청	데이터마다 다름(즉시 승인 또는 담당자 확인)
목록에 없는 데이터가 필요하다	제공신청	기관이 10일 이내에 제공 여부 통보
제공 거부나 중단 처분을 받았다	분쟁조정 신청	처분을 받은 날부터 60일 이내에 신청

아직 모르는 것과 이 글의 한계

호출 한도를 정확히 파악하지 못했습니다. 일일 한도가 있다고 적혀 있지만 실제로 걸려 본 적이 없어서 어떻게 표시되는지 모릅니다. 방문자가 늘어나면 확인해야 할 부분입니다. 앞에서 본 429 상태 번호가 한도에 걸렸을 때 나올 수 있는 신호라는 정도만 알고 있습니다.

또 이 글은 제가 쓴 한 종류의 API를 기준으로 합니다. 공공데이터포털에는 형식이 다른 API가 많아서 그대로 맞지 않을 수 있습니다. 응답 형식이나 필드 이름, 키를 넣는 방식은 데이터마다 다르니 각 데이터의 상세 화면과 개발 가이드를 먼저 읽는 것을 권합니다.

마지막으로, 키 반영에 걸린 시간과 승인 방식은 제가 겪은 경험입니다. 정확한 기준이 필요하면 포털의 공식 안내를 확인하세요.

그래서 이 글을 따라 할 때는 아래 세 가지를 스스로 확인하는 것이 좋습니다.

• 내가 쓸 데이터의 승인 방식이 즉시인지 담당자 확인인지
• 키를 어떤 형태로 주소에 넣어야 하는지
• 응답의 필드 이름이 문서와 실제가 같은지

이 세 가지는 제가 막혔던 곳이기도 합니다. 처음부터 의심하고 시작하면 시간을 크게 줄일 수 있습니다.

함께 보면 좋은 글

• 제미나이 4 아르곤, 누가 어떻게 시작하나
• AI 에이전트가 일을 맡는 세 단계
• [마이 프로젝트] 공공데이터 API 키 숨기기: 블로그에 안 보이게
• [마이 프로젝트] 공공데이터 API 호출 제한: 1,000건씩 나눠 받기
• [마이 프로젝트] 블로그에 영화 순위 넣는 무료 API 3곳

확인 자료

• 공공데이터포털, 공공데이터 안내 : 오픈 API 활용신청, 목록 검색, 제공신청 처리 기간, 분쟁조정
• MDN Web Docs, encodeURIComponent() : 변환 제외 문자 목록과 주소 값 변환 예시
• MDN Web Docs, HTTP 응답 상태 코드 : 401, 403, 404, 429, 500의 의미