할당량 및 속도 제한

이용 범위를 정하는 제한은 두 가지입니다. 요금제에서 하루에 허용하는 검색 횟수와, 요청을 보낼 수 있는 속도입니다. 두 가지 모두 매 응답에 포함되므로, 클라이언트는 일부러 오류를 일으켜 한계를 확인하지 않고도 요청 속도를 스스로 조절할 수 있습니다.

속도 제한: 분당 10회

제한은 계정 단위이며 API와 MCP 서버가 함께 씁니다. 어느 쪽으로 보내든 1분에 10회까지입니다. 같은 1분 안에 11번째 요청을 보내면 즉시 429 too_many_requests와 함께, 다음 요청이 가능해질 때까지 남은 초를 알려 주는 Retry-After 헤더가 반환됩니다. 같은 값이 본문의 error.retry_after에도 들어 있습니다.

HTTP/2 429
Retry-After: 18

{ "error": { "code": "too_many_requests",
             "message": "At most 10 requests per minute.",
             "retry_after": 18 } }

Retry-After초만큼 기다렸다가 요청을 다시 보내세요. 아무것도 처리되지 않았고 할당량도 차감되지 않았습니다.

API는 속도를 늦추려고 연결을 붙잡아 두지 않습니다. 기존 내보내기 URL은 그렇게 합니다. 1초씩 최대 30초까지 대기한 뒤 요청을 거부하는데, 이것이 API를 만든 이유 중 하나입니다.

일일 할당량

요금제마다 하루 검색 횟수와 하루 스니펫 요청 횟수가 정해져 있으며, 따로 집계됩니다. 둘 다 사용 후 24시간이 아니라 다음 UTC 자정에 초기화됩니다.

• 검색 1회는 검색 할당량에서 1회가 차감됩니다.
• snippets=1을 지정한 검색은 대신 스니펫 할당량에서 1회가 차감됩니다.
• /v1/account는 차감되지 않습니다.

할당량을 다 쓰면 요청은 429 quota_exceeded 또는 429 snippet_quota_exceeded로 거부되며, 한도와 사용량, 초기화까지 남은 시간이 함께 전달됩니다. 스니펫 할당량을 다 써도 일반 검색은 계속할 수 있습니다.

결과 공개 범위

요금제는 순위의 어디까지 결과를 공개할지도 정합니다. /v1/account의 disclosed_positions입니다. 그 범위를 넘는 행은 빈칸으로 두지 않고 아예 제외하며, 제외된 행이 있으면 본문의 truncated가 true, 헤더에는 X-Truncated: true가 들어갑니다.

이것이 API와 웹사이트의 가장 중요한 차이입니다. 브라우저에서는 할당량을 다 쓰면 조용히 무료 요금제의 공개 범위로 돌아가 결과를 적게 보여 주며, 페이지를 보는 사람에게는 이것으로 충분합니다. 하지만 스크립트는 이를 알아챌 수 없으므로, API는 결과를 줄이는 대신 요청을 거부합니다.

현재 상태 확인하기

인증된 모든 응답에는 다섯 가지 헤더가 포함됩니다.

검색 결과에는 세 가지 헤더가 더 포함됩니다.

사용량 통계

/v1/account를 한 번 호출하면 전체 현황을 알 수 있으며, 할당량도 차감되지 않습니다.

curl -H "Authorization: Bearer $KEY" https://api.publicwww.com/v1/account

{
  "plan": "enterprise",
  "plan_until": 1819461840,
  "full_access": true,
  "quota": {
    "searches": { "limit": 300, "used": 12, "resets_at": 1787961600 },
    "snippets": { "limit": 100, "used": 3,  "resets_at": 1787961600 }
  },
  "limits": {
    "disclosed_positions": 4294967295,
    "disclosed_positions_snippets": 4294967295,
    "max_per_page": 1000000,
    "max_per_page_snippets": 10000
  }
}

기존의 https://publicwww.com/profile/api_status.xml?key=...도 같은 사용량을 XML로 알려 주며 여전히 작동합니다. 다만 이것은 기존 URL에 속하므로, 새 코드에서는 사용량뿐 아니라 한도까지 알려 주는 /v1/account를 사용하세요.