공공데이터 API로 만든 도구가 하루 454번 만에 멈추는 이유

공공데이터포털의 개발계정 한도는 하루 10,000건입니다. 그런데 제가 만든 화면은 검색 한 번에 22번을 부르고 있었습니다. 나누면 454번입니다.

공공데이터 오픈API로 뭔가 만들어보려는 1인 개발자와 비개발자를 독자로 두고 씁니다.

결론부터 적습니다. 이 API로 도구를 만들 때 첫 설계 결정은 화면이 아니라 산수에서 나옵니다. 저는 그 산수를 나중에 했고, 그래서 다 만든 로직을 한 번 뒤집었습니다.

왜 검색 한 번에 22번을 부르게 되는가?

두 창구를 이어 붙여야 하고, 각각 열한 쪽이기 때문입니다. 다만 이건 이 데이터의 사정이지 모든 공공데이터가 그렇다는 뜻은 아닙니다.

이 데이터는 목록(serviceList)과 지원조건(supportConditions) 두 엔드포인트로 갈라져 있습니다. 목록에는 사업명·소관기관이 있고, 조건에는 나이·소득·가구 형태가 있어요. 둘을 서비스ID로 붙여야 "나한테 맞는지"를 판단할 수 있습니다.

전체는 10,968건이고 한 쪽에 1,000건씩 받으면 11쪽입니다. 두 엔드포인트니까 22번입니다.

왜 조건을 붙여 부르면 안 되는가?

cond 파라미터가 조용히 무시되기 때문입니다. 에러가 나지 않는다는 점이 이 함정의 핵심입니다.

1인가구·근로자 같은 코드를 다섯 가지 조합으로 넣어봤습니다. 응답 상태는 매번 200이었고 형식도 흠이 없었어요. 그런데 전체 건수가 조건 없이 부른 값에서 한 자리도 움직이지 않았습니다.

서버가 거절한 게 아니라 받지 않은 것입니다. 거절이면 코드가 돌아오고, 무시는 아무 신호도 남기지 않아요. 그래서 저는 한동안 서버가 아니라 제 파라미터 문법을 의심하고 있었습니다.

하루 454번은 실제로 어떤 상태인가?

검색 454번이면 그날 도구가 멈춥니다. 사람 수가 아니라 검색 횟수 기준이라 체감보다 훨씬 빨리 도달합니다.

한 사람이 조건을 바꿔가며 세 번 검색하면 66호출입니다. 하루 150명이 들어와 각자 세 번씩 눌러보면 그날 한도를 넘습니다. 링크를 공유하는 순간 도달할 수 있는 숫자예요.

여기서 선택지가 둘로 갈립니다.

	실시간 호출	스냅샷 파일
검색 1회당 정부 호출	22	0
하루 한계	454회 검색	없음
데이터 신선도	실시간	수집 시점 고정
인증키가 배포물에	들어간다	안 들어간다
사용자 몰림	도구가 멈춤	영향 없음

같은 조건에서 비교하면 실시간 쪽이 신선도 하나를 얻고 나머지를 전부 내줍니다. 반면 스냅샷은 신선도만 포기합니다. 정부 혜택 정보는 초 단위로 바뀌는 종류가 아니라, 저는 이 교환이 남는 장사라고 봤습니다.

스냅샷으로 바꾸면 인증키는 어디로 가는가?

내 컴퓨터에만 남습니다. 배포물에 키가 들어갈 경로 자체가 사라지기 때문입니다.

실시간 호출 방식이면 브라우저가 정부 서버를 직접 부르거나, 그걸 감추려고 중계 서버를 하나 세워야 합니다. 전자는 키가 화면 소스에 노출되고, 후자는 서버 코드와 환경변수를 관리해야 해요.

스냅샷은 그 선택 자체가 없어집니다. 키가 쓰이는 곳은 수집 스크립트 한 군데고, 그건 제 컴퓨터에서 한 번 돕니다. 인터넷에 올라가는 건 화면·데이터·수집 스크립트·설명 파일 네 개인데, 수집 스크립트를 주소로 열어봐도 키가 들어갈 곳에는 변수 이름만 있습니다.

확인은 짐작이 아니라 관측으로 했습니다. 개발자 도구 네트워크 탭에서 나가는 요청은 자기 페이지와 데이터 파일 두 개뿐이었고, /.env를 직접 쳐도 404가 떴습니다. 환경변수는 한 개도 걸려 있지 않습니다.

이 결과가 흥미로운 건, 보안을 목표로 설계한 게 아니라는 점입니다. 하루 한도 때문에 바꾼 방식이 키 노출 문제를 부수효과로 없앴습니다.

걸러내는 규칙은 어디서 무너졌는가

여기서 제 첫 버전이 틀렸습니다.

조건표의 코드를 그대로 읽어 걸렀습니다. 연령 범위가 맞고 성별이 맞고 소득 구간이 맞으면 통과시켰어요. 그렇게 돌린 첫 결과의 최상단은 수출 기업용 물류 지원사업이었습니다.

원인은 하나였습니다. 대상이 누구인지를 제가 안 보고 있었습니다.

대상 구분 필드를 아예 읽지 않았고, 조건 묶음마다 붙은 "안 따짐" 표시를 어떻게 볼지 정하지 않았고, 지역은 당연히 있을 거라 가정했습니다. 세 가지 다 확인 없이 넘어간 것들입니다.

그래서 방향을 바꿨습니다. 코드가 맞는지를 보는 게 아니라, 정부가 이 사람을 대상으로 콕 집어 적었는지를 보는 쪽으로요.

해당사항없음을 통과시켜야 하는가?

정답은 없고, 정한 뒤 화면에 적어야 합니다. 어느 쪽을 골랐는지 밝히지 않으면 숫자가 3.6배 흔들립니다.

"안 따짐" 표시는 묶음별로 따로 붙습니다. 가구 쪽이 8,991건, 신분 쪽이 4,312건이에요. 해당 묶음에서 대상을 가리지 않는 사업이라는 신호입니다.

통과시키면 — 나를 배제하지 않는 것까지 전부 걸려서 377개
통과시키지 않으면 — 나를 콕 집어 대상으로 적은 것만 남아서 105개

저는 105 쪽을 택했습니다. 느슨하게 세면 숫자만 커지고 내가 대상인지는 여전히 모르거든요.

다만 이건 제 판단이고, 최대한 많이 보고 싶은 사람에게는 377이 맞을 수 있습니다. 중요한 건 어느 쪽이든 화면에 그 기준을 적는 것입니다.

지역 조건이 없는 데이터에서 지역을 어떻게 판단하는가?

소관기관 이름으로 판단합니다. 다만 이 방식은 양쪽으로 다 샙니다.

조건표를 다 뒤져도 지역 항목이 없습니다. 나이도 소득도 가구 형태도 있는데 사는 곳만 없어요. 그래서 목록 쪽에 있는 소관기관명과 소관기관유형을 씁니다.

기관유형 분포는 이렇습니다.

기관유형	건수
시군구	6,516
광역시도	1,391
중앙행정기관	1,052
공공기관	603
지방출자·출연기관	584
지방공기업	561
교육청	261

여기서 눈여겨볼 건 아래 두 줄입니다. 지방출자기관과 지방공기업 1,145건이 기관유형상 시군구가 아닙니다. 그래서 시·도 이름만 보고 통과하게 됩니다.

이 규칙에서 무엇이 새는가

두 방향으로 샙니다. 놓치는 쪽과 들어오는 쪽입니다.

놓치는 쪽 — 동네 이름만 대조하면 광역 단위 사업이 전부 탈락합니다. 문자열 포함 관계로는 상위 행정구역이 하위를 담지 못하니까요. 그래서 입력받는 항목을 둘로 쪼갰습니다.

들어오는 쪽 — 이건 한참 뒤에 세어보고 알았습니다. 지역으로 분류된 31건 가운데 14건이 다른 자치구 산하 공단 사업이었어요. 원인은 기관유형 분류에 있습니다. 공단·출자기관은 시군구로 잡히지 않아서 광역 이름만으로 통과합니다.

첫 번째는 고쳤고 두 번째는 아직 남아 있습니다. 기관유형이 지방공기업·출자기관이면 기관명에서 구 단위까지 맞추는 조건을 하나 더 걸어야 합니다.

다른 데이터로 옮길 때 무엇을 다시 짜는가?

수집과 필터만 다시 짭니다. 나머지는 데이터가 달라져도 구조가 같습니다.

그대로 쓰는 것 — 신청·키 발급 절차, 스냅샷 결정, 배포 명령, 키 노출 검증
다시 짜는 것 — 엔드포인트 이어 붙이는 방식, 조건 코드 해석, 지역 판단 규칙

판단 지점도 그대로입니다. 새 데이터를 만날 때마다 이 순서로 물으면 됩니다. 조건 검색이 서버에서 먹는가, 검색 1회당 호출이 몇 번인가, 하루 한도를 그 수로 나누면 몇인가.

정리 — 확인할 세 가지

이 글에서 다룬 함정이 셋이었으니 확인할 것도 셋입니다.

조건이 진짜 서버에서 걸리는지 전체 건수 변화로 검증하세요. 무응답이 아니라 무반응이 문제입니다.
한도를 호출 배수로 나눠보세요. 그 몫이 도구의 수명이고, 설계는 거기서 갈립니다.
바깥으로 나가는 통신을 직접 세어보세요. 외부 도메인이 하나라도 잡히면 키가 어딘가 실려 있습니다.

제가 이 글에서 틀릴 수 있는 문장은 두 번째 표의 "영향 없음"입니다. 스냅샷도 파일이 커지면 첫 로딩에서 걸리고, 저는 12.6MB를 4.8MB로 줄이고서야 브라우저가 버티는 걸 봤습니다. 무한히 안전한 방식은 아닙니다.

어느 데이터를 만져보고 계신가요? 조건 검색이 먹는지부터 확인해보시면 설계가 반쯤 정해집니다.