Postcodify 매뉴얼

쿼리수 제한 및 가중치 안내

쿼리수 제한 개요

무료 API는 검색서버의 원활한 운영과 공평한 사용을 위해 도메인당, 클라이언트 IP당 각각 일일 쿼리수 제한을 두고 있습니다. (검색서버를 직접 구축하신 경우에는 해당되지 않습니다.)

  • 도메인당 제한: 하루 10,000회
  • IP당 제한: 하루 1,000회

집계 기준 상세 설명

  • “하루”는 대한민국 표준시를 기준으로 자정부터 다음날 자정까지로 합니다.
  • 도메인은 jQuery 플러그인을 실제 사용하는 웹 페이지가 소속된 도메인을 가리키며, abcd.com, abcd.co.kr, abcd.kr 등 일반적으로 등록 가능한 1차도메인을 기준으로 합니다. 여러 서브도메인을 만들어 사용하더라도 모두 하나의 도메인으로 취급합니다.
  • 널리 알려진 웹호스팅 업체, RDNS 서비스 등에서 제공하는 2차도메인은 관리자의 판단에 따라 별도의 도메인으로 취급할 수도 있습니다. 현재 *.cafe24.com, *.iptime.org 등이 이런 정책의 적용을 받고 있습니다.
  • 테스트용 사이트, 인트라넷 등에서 별도의 도메인 없이 서버의 IP를 그대로 사용하는 경우, 서버의 IP를 도메인으로 취급합니다.
  • 클라이언트 IP는 실제 주소 검색을 수행하는 사용자의 IP를 가리키며, 서버의 IP와는 무관합니다.

검색 형태에 따른 가중치 적용

Postcodify는 도로명주소, 지번주소, 영문주소, 사서함, 건물명 등 다양한 형태의 검색어를 허용합니다. 그러나 모든 검색어가 서버에 동일한 부담을 주지는 않으며, 도로명주소의 특성상 모든 검색어가 항상 사용자에게 유용한 결과를 반환할 수도 없습니다. 따라서 실제로 검색에 소요되는 시간과 자원, 검색 결과의 정확도 등을 감안하여 아래와 같이 가중치를 부여합니다.

검색 형태 검색 예 가중치
도로명주소 (건물번호 포함) 세종대로 110 1
지번주소 (번지수 포함) 연산동 1000 1
사서함 사서함 35-12 1
도로명 (건물번호 없음) 동작대로 2
건물명 주공아파트 4
읍·면 등 지방행정구역 명칭으로만 검색 가남읍 8
동·리만 입력하고 번지수 없음 신림동 16

가중치가 높은 검색을 많이 수행할 경우 일일 쿼리수 제한에 빨리 도달하게 됩니다. 예를 들어 건물번호가 포함된 도로명주소는 도메인당 하루 10,000회 검색할 수 있지만, 동·리만 입력하는 검색을 반복할 경우 도메인당 하루 625회밖에 검색할 수 없게 됩니다.

쿼리수 제한 초과시 조치

도메인당 쿼리수 제한을 초과하더라도 즉시 검색이 중단되지는 않으나, 심하게 초과하거나 상습적으로 초과하는 경우 관리자의 판단에 따라 검색을 제한할 수 있으며, 쿼리수 제한을 초과하였음을 알리는 메시지가 사용자들에게 노출될 수 있습니다.

IP당 쿼리수는 악의적 공격을 막기 위해 도메인당 쿼리수 제한보다 더 엄격하게 제한하고 있습니다.

이벤트, 캠페인 등으로 일시적인 쿼리수 폭증이 예상되는 분은 최소한 3일 전에 kijin@poesis.org로 미리 연락해 주시면 가능한 범위 내에서 원활하게 검색이 이루어지도록 배려해 드리겠습니다.

사전 협의 없이 쿼리수 제한을 초과하는 경우 주소 검색이 원활하지 못하여 회원들이 가입하지 못하거나 이벤트에 참여하지 못하는 불상사가 발생할 수 있으니 반드시 미리 연락해 주시면 감사하겠습니다.

도로명주소 시행 초기여서 많은 분들이 검색에 어려움을 겪고 있습니다. Postcodify는 일반적인 사용자들의 검색 패턴을 최대한 배려하여 개발하였으나, 여전히 한 사람이 3~5회씩 검색하는 경우가 많으니 쿼리수 계산시 참고하시기 바라고, 가능하면 requireExactQuery 옵션을 사용하여 정확한 검색을 유도하여 주시기 바랍니다.

지속적으로 쿼리수가 초과될 것으로 예상되는 웹사이트라면 직접 검색서버를 구축하시거나, 월 1만원 이상 API 운영비를 후원하는 스폰서가 되어 주시기 바랍니다. 스폰서는 가능한 범위 내에서 쿼리수 걱정 없이 사용하실 수 있도록 배려해 드리겠습니다.

후원이 부담스러운 소규모의 비영리단체라면 별도로 문의해 주시기 바랍니다.

기타 정보

위의 쿼리수 제한은 2014년 10월 12일부터 적용됩니다.

예전에는 도메인당 쿼리수 제한이 하루 1,000회였으며 검색 형태에 따른 가중치는 적용하지 않았습니다. 변경된 정책은 사용자들에게 올바른 주소검색 습관을 권장하는 웹사이트에 최대 10배의 검색을 허용하지만, 그렇지 않은 웹사이트에는 페널티를 부여하는 것을 목적으로 합니다.

실제 검색 요청의 가중치 평균은 2014년 6.67 → 2019년 2.19 → 2021년 1.78을 기록하고 있습니다. 사용자들이 도로명주소 검색에 익숙해짐에 따라 정확한 검색의 비율이 계속 늘어나고 있습니다.

무료 API를 최대한 활용하려면 건물번호 또는 번지수까지 입력하여 검색하도록 사용자들을 적극 유도하고, requireExactQuery 옵션을 사용하여 가중치가 높은 검색이 발생하지 않도록 하는 것을 권장합니다.