crawl-census-client

가져오기 전에 물어보세요. 크롤러가 닫힌 문에 요청을 낭비하지 않고, 누군가 팔려는 콘텐츠를 우회하지 않도록 막아주는 드롭인 클라이언트입니다.

robots.txt를 읽는 것은 하나의 질문에 답하고 두 가지를 숨깁니다. Crawl Census가 측정한 23,482개 도메인 기준:

• 2,874개 도메인은 robots.txt에서 AI 에이전트를 허용하면서도 네트워크 경계에서 동일한 에이전트를 거부합니다. 파서는 허가를 보고, 가져오기는 403을 반환합니다. 왕복 비용을 지불하고 아무것도 얻지 못합니다.

• 208개 도메인은 AI 사용자 에이전트에 HTTP 402 Payment Required로 응답합니다. 그것은 거부가 아니라 가격입니다. 차단으로 취급하면 운영자가 판매하려는 콘텐츠에서 발을 빼는 것입니다. 우회해서 재시도하면 요금을 청구하는 것을 가져가는 것입니다.

의존성 없음. 키 불필요.

MCP 서버

동일한 측정이 원격 MCP 서버로 노출되어, 에이전트가 실패한 후가 아니라 가져오기 전에 물어볼 수 있습니다. 공식 MCP 레지스트리에 io.github.taylorsmithgg/crawl-census로 등재되어 있습니다.

{ "mcpServers": { "crawl-census": { "url": "https://crawlcensus.com/mcp" } } }

읽기 도구에 인증 불필요. Streamable HTTP.

Related MCP server: Maango-mcp

설치

npm i github:taylorsmithgg/crawl-census-client
pip install git+https://github.com/taylorsmithgg/crawl-census-client

사용

import { politeFetch } from "crawl-census-client";

const r = await politeFetch("https://example.com/", { agent: "gptbot" });
if (r.skipped) console.log(r.verdict, r.reason);   // disallow | refuse | pay
else           process(await r.response.text());

from crawl_census import polite_fetch

r = polite_fetch("https://example.com/", agent="gptbot")
if r.skipped:
    print(r.verdict, r.reason)
else:
    process(r.body)

건너뛰기는 발생시키지 않고 반환됩니다. 웹의 상당 부분에서 정상적인 결과이며, 크롤 루프는 모든 URL에 try/except 없이 건너뛰기를 셀 수 있어야 합니다.

크롤링 전에 큐 분할

호스트당 한 번이 아니라 1,000개 도메인당 한 번 호출:

const { crawl, skip, pay, unknown } = await partition(urls, { agent: "gptbot" });

p = partition(urls, agent="gptbot")
p.crawl, p.skip, p.pay, p.unknown

아니면 그냥 파일을 가져가세요

메모리에 거부 목록만 필요한 페처라면 도메인별 호출을 완전히 건너뛰세요:

curl https://crawlcensus.com/agents/gptbot/blocklist.txt   # one domain per line, commented header

const sync = await syncBlocklist("gptbot");   // full list once
if (sync.blocked.has(host)) skip();
setInterval(() => sync.refresh(), 3600_000);  // then deltas only, a few hundred bytes

sync = BlocklistSync("gptbot")
if host in sync: skip()
sync.refresh()          # {'added': 3, 'removed': 1, 'size': 3310, 'cursor': ...}

델타 피드는 https://crawlcensus.com/agents/<agent>/changes.json?since=<unix>이며 각 응답은 next_since를 전달하므로, 장기 실행 크롤러는 목록을 다시 다운로드하는 대신 시간당 수백 바이트로 최신 상태를 유지합니다.

그 파일은 robots.txt만 다룹니다. 경계 거부와 HTTP 402는 요청별 동작이므로 여전히 preflight 또는 politeFetch가 필요합니다.

크롤이 인구조사에 드는 비용

주장이 아닌 측정입니다. 동시에 가져온 20개 호스트는 각각 하나의 도메인을 담은 20번의 preflight 호출이 들었습니다. 같은 호스트를 세 번 동시에 요청하면 첫 조회가 해결된 후에만 캐시가 도움이 되므로 세 번의 비용이 들었습니다. 익명 허용량은 시간당 240회 호출이므로, 한 번 호출로 25개를 처리할 수 있을 때 크롤러는 240개 호스트에서 한계에 도달했습니다.

politeFetch는 이제 자동으로 작업을 공유합니다: 같은 틱에서 발행된 조회는 하나의 배치 호출로 나가고, 같은 호스트에 대한 동시 조회는 단일 요청을 기다립니다.

batchSize는 키 없이 호출당 상한인 25가 기본값입니다. Pro 또는 Data 키로 올리세요. batchWaitMs는 한 번에 도착하는 것이 아니라 파도처럼 도착하는 동시성에 대한 병합 창을 넓힙니다. 기본값 0은 다음 틱에 플러시합니다.

출처가 가격을 제시할 때 지불

pay 판정은 출처가 금액을 명시했을 때 그 금액을 전달합니다:

const r = await politeFetch(url, { agent: "claudebot" });
if (r.verdict === "pay") console.log(r.price);   // "USD 0.5", or null if none was quoted

알아둘 두 가지가 있습니다. HTTP 402로 응답하는 대부분의 출처는 금액을 전혀 명시하지 않으므로 price는 보통 null이고 계약은 대역 외로 체결해야 합니다. 그리고 가격은 크롤러별로 다릅니다: 측정된 코퍼스에서 213개 청구 출처 중 78개는 일부 에이전트에게 청구하고 다른 에이전트에게는 무료로 서빙하므로, 목록에 있는 도메인이 당신에게 청구할 것이라고 가정하지 말고 자신의 토큰으로 물어보세요.

두 종류의 미지

partition은 작업 큐를 crawl, pay, skip, unknown, undecidable로 분할합니다.

마지막 두 개는 비슷해 보이지만 다릅니다. unknown은 인구조사가 아직 그 도메인을 측정하지 않았다는 뜻입니다: 제출하면 다음 패스에서 실제 판정을 받습니다. undecidable은 사이트의 robots.txt가 CrawlCensusBot을 허용하지 않아 이 인구조사가 결코 측정하지 못한다는 뜻입니다 — 재시도는 보장된 낭비이며, 매 패스 미지를 재제출하는 루프는 그것들을 영원히 재제출할 것입니다. 서버는 measurable 불리언으로 차이를 표시합니다. reason 문구가 아니라 그것을 읽으세요.

const p = await partition(urls, { agent: "gptbot" });
await Promise.all(p.crawl.map(politeFetchOne));
if (p.unmeasured.length) await submitUnmeasured(p, { agent: "gptbot" });
// p.undecidable: read their robots.txt yourself. Asking us again cannot help.

제출은 의도적으로 별도의 호출입니다. 조회처럼 보이는 동안 조용히 POST하는 라이브러리는 나쁜 시민이며, 큐 위치가 언제 소비될지 선택해야 합니다.

당신을 서빙하지 않을 모든 것 건너뛰기

거부 목록은 작은 절반입니다. 실시간 인구조사에 대해 측정했을 때, robots disallow만 건너뛰는 크롤러는 robots.txt에서 허용하면서 경계에서 거부하거나 HTTP 402로 응답하는 도메인에 패스당 약 2,900회의 요청을 여전히 소비합니다 — PerplexityBot의 경우 그 집합이 거부 목록보다 큽니다. 그 가져오기들은 아무것도 반환하지 않고 각각 왕복 비용이 듭니다.

const skip = await syncSkipList("gptbot");
if (skip.has(host)) continue;        // disallowed, refused at the edge, or priced
skip.why(host);                      // "disallow" | "pay" | "refuse" | null
setInterval(() => skip.refresh(), 3600_000);

세 집합은 내부적으로 분리되어 있어 변경이 속한 집합만 이동합니다. why()는 preflight와 같은 우선순위를 따릅니다: disallow가 가격보다 우선합니다. 가격은 허가가 아니기 때문입니다.

거부 목록 최신 상태 유지

syncBlocklist / BlocklistSync는 목록을 한 번 다운로드한 다음 변경된 것만 적용합니다.

목록은 빌드된 변경 피드의 정확한 위치와 함께 x-cursor 헤더와 # cursor: 주석으로 제공됩니다. 클라이언트는 그것을 읽고 거기서 재개하므로 스냅샷과 첫 폴링 사이에 공백이 없고, 서버와 시계가 일치할 필요도 없습니다. 초 단위 폴링은 초 내부의 위치를 표현할 수 없고, 크롤 배치는 수십 개의 이벤트를 한 초에 쓰므로 초 단위 재개는 나머지를 놓칠 수 있습니다: 실시간 측정에서 같은 초의 세 가지 변경 중 첫 번째 후 재개했을 때 커서로는 형제 둘 다 복구했지만 초로는 둘 다 복구하지 못했습니다.

const sync = await syncBlocklist("gptbot");   // cursor comes from the list itself
if (sync.blocked.has(host)) skip();
setInterval(() => sync.refresh(), 3600_000);  // a few hundred bytes per poll

refresh()는 목록에 robots 전환만 적용합니다. 목록이 그것으로 구성되어 있기 때문입니다. 경계 거부, 새 가격, llms.txt 변경은 other로 돌아와 별도로 처리할 수 있습니다 — 이전 버전은 그 도메인들을 거부 목록에서 삭제하여 크롤러가 막 거부를 시작한 것을 정확히 다시 가져오기 시작했습니다.

판정

각 판정의 권위 있는 정의 — 의미, 크롤러가 해야 할 일, 다시 물어보면 바뀔 수 있는지 — 는 /api/v1/verdicts에 데이터로 게시되어 있습니다. 아래 목록은 요약입니다. 둘이 다르다면 엔드포인트가 맞고 이 파일이 낡은 것입니다.

politeFetch는 기본적으로 disallow, refuse, pay를 건너뛰며, 이는 엔드포인트의 파생 do_not_fetch 집합입니다. 여기의 복사본은 의도적입니다 — 크롤 루프는 결정을 위해 네트워크 호출이 필요하지 않아야 하며 — 테스트가 둘을 비교하여 눈에 띄지 않게 표류할 수 없게 합니다.

onPay: "fetch" (on_pay="fetch")는 페이월 기본값을 재정의합니다. 명시적 옵트인이며 결과에 paidRouteOverridden으로 기록되어 로그에 표시됩니다.

저하되지만 실패하지 않음

인구조사에 연결할 수 없으면 모든 판정이 unknown이 되고 크롤은 평소처럼 진행됩니다. 제3자 장애가 파이프라인을 멈춰서는 안 됩니다. 정확히 이것을 위한 실시간 테스트가 있습니다.

우리가 당신의 에이전트에 대해 게시하는 것

const p = await agentProfile("claudebot");
// robots disallow rate, edge refusal rate, operator page, correction channel

수치가 틀렸다면 수정 채널이 그 응답과 운영자 페이지에 있습니다. 레지스트리 사실은 논쟁 없이 수정됩니다. 논쟁이 있는 측정은 조용히 수정하는 대신 기본 스캔 기록과 함께 논쟁과 함께 게시됩니다.

한도

익명으로 preflight 호출당 25개 도메인, Pro 키로 200개, Data 키로 1,000개. apiKey를 전달하세요. 자세한 내용은 https://crawlcensus.com/for-crawlers.

테스트

node test.mjs는 의도적으로 실시간 인구조사에 대해 실행됩니다. 이 클라이언트의 가치는 판정이 현실과 일치하는지이며, 모의 테스트는 모의가 자신과 일치한다는 것만 주장할 것입니다.

MIT. 데이터는 CC BY 4.0, 출처 표시는 "Source: Crawl Census (crawlcensus.com)".