crawl-census-client

Fragen, bevor du abrufst. Ein Drop-in-Client, der deinen Crawler davon abhält, Anfragen an Türen zu verschwenden, die geschlossen sind, und der verhindert, dass er Inhalte umgeht, die jemand verkaufen möchte.

Das Lesen von robots.txt beantwortet eine Frage und versteckt zwei andere. Gemessen über 23.482 Domains von Crawl Census:

• 2.874 Domains erlauben KI-Agenten in robots.txt und verweigern denselben Agenten dann an der Netzwerkgrenze. Ein Parser sieht die Erlaubnis; der Abruf liefert 403. Du zahlst für den Roundtrip und bekommst nichts.

• 208 Domains antworten einem KI-User-Agent mit HTTP 402 Payment Required. Das ist ein Preis, keine Ablehnung. Es als Blockade zu behandeln, geht an Inhalten vorbei, die der Betreiber dir verkaufen möchte. Ein erneuter Versuch nimmt etwas, wofür sie Geld verlangen.

Keine Abhängigkeiten. Kein Schlüssel erforderlich.

MCP-Server

Dieselbe Messung wird als Remote-MCP-Server bereitgestellt, sodass ein Agent fragen kann, bevor er abruft, statt nachdem es fehlschlägt. Gelistet im offiziellen MCP-Registry als io.github.taylorsmithgg/crawl-census.

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

Keine Authentifizierung für Lese-Tools. Streamable HTTP.

Related MCP server: Maango-mcp

Installation

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

Verwendung

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)

Überspringen wird zurückgegeben, nicht ausgelöst. Es ist das normale Ergebnis für einen großen Teil des Webs, und eine Crawl-Schleife sollte Überspringungen zählen können, ohne ein try/except um jede URL zu legen.

Eine Warteschlange vor dem Crawlen aufteilen

Ein Aufruf pro 1.000 Domains statt einer pro Host:

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

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

Oder einfach die Datei nehmen

Für einen Fetcher, der nur eine Deny-Liste im Speicher benötigt, überspringe die Pro-Domain-Aufrufe vollständig:

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': ...}

Der Delta-Feed ist https://crawlcensus.com/agents/<agent>/changes.json?since=<unix> und jede Antwort trägt next_since, sodass ein langlaufender Crawler mit ein paar hundert Bytes pro Stunde aktuell bleibt, statt die Liste erneut herunterzuladen.

Diese Datei deckt nur robots.txt ab. Edge-Ablehnung und HTTP 402 sind Verhaltensweisen pro Anfrage und benötigen weiterhin preflight oder politeFetch.

Was ein Crawl die Volkszählung kostet

Gemessen, nicht behauptet. Zwanzig gleichzeitig abgerufene Hosts kosteten früher zwanzig Preflight-Aufrufe mit je einer Domain; derselbe Host dreimal gleichzeitig angefordert kostete drei, weil der Cache erst nach der ersten Lookup-Auflösung hilft. Das anonyme Kontingent beträgt 240 Aufrufe pro Stunde, sodass ein Crawler sein Limit bei 240 Hosts erreichte, wenn ein Aufruf fünfundzwanzig abdeckt.

politeFetch teilt die Arbeit jetzt automatisch: Lookups, die im selben Tick ausgegeben werden, gehen als ein gebündelter Aufruf raus, und gleichzeitige Lookups für denselben Host warten auf eine einzige Anfrage.

batchSize standardmäßig 25, das Pro-Aufruf-Limit ohne Schlüssel. Erhöhe es mit einem Pro- oder Data-Schlüssel. batchWaitMs erweitert das Zusammenführungsfenster für Nebenläufigkeit, die in Wellen statt auf einmal ankommt; der Standardwert von null leert beim nächsten Tick.

Bezahlen, wenn eine Quelle einen Preis nennt

Ein pay-Urteil trägt den Betrag, wenn die Quelle einen genannt hat:

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

Zwei Dinge sind wissenswert. Die meisten Quellen, die mit HTTP 402 antworten, nennen überhaupt keinen Betrag, also ist price normalerweise null und die Vereinbarung muss außerhalb der Reihe getroffen werden. Und die Preisgestaltung ist pro Crawler: Im gemessenen Korpus berechnen 78 von 213 kostenpflichtigen Quellen einigen Agenten Gebühren und bedienen andere kostenlos, also frage mit deinem eigenen Token, statt anzunehmen, dass eine Domain auf der Liste dich zur Kasse bittet.

Zwei Arten von Unbekannt

partition teilt eine Arbeitswarteschlange in crawl, pay, skip, unknown und undecidable.

Die letzten beiden sehen ähnlich aus und sind es nicht. unknown bedeutet, dass die Volkszählung diese Domain noch nicht gemessen hat: Reiche sie ein und der nächste Durchgang erhält ein echtes Urteil. undecidable bedeutet, dass die robots.txt der Website CrawlCensusBot nicht erlaubt, sodass diese Volkszählung sie nie messen wird – ein erneuter Versuch ist garantierte Verschwendung, und eine Schleife, die ihre Unbekannten bei jedem Durchgang erneut einreicht, würde diese für immer erneut einreichen. Der Server markiert den Unterschied mit einem measurable-Boolean; lies das, niemals den reason-Prosa.

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.

Die Einreichung ist absichtlich ein separater Aufruf. Eine Bibliothek, die während eines Lookups stillschweigend POSTs, ist ein schlechter Bürger, und du solltest wählen, wann deine Warteschlangenpositionen ausgegeben werden.

Alles überspringen, was dir nicht dienen wird

Eine Deny-Liste ist die kleinere Hälfte. Gemessen an der Live-Volkszählung gibt ein Crawler, der nur robots-Verbote überspringt, immer noch etwa 2.900 Anfragen pro Durchgang für Domains aus, die es in robots.txt erlauben und an der Grenze ablehnen, oder die mit HTTP 402 antworten – für PerplexityBot ist diese Menge größer als seine Deny-Liste. Diese Abrufe liefern nichts und kosten jeweils einen Roundtrip.

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);

Die drei Mengen werden intern getrennt gehalten, sodass eine Änderung diejenige verschiebt, zu der sie gehört. why() folgt derselben Priorität wie Preflight: Ein Verbot hat Vorrang vor einem Preis, weil ein Preis keine Erlaubnis ist.

Eine Deny-Liste aktuell halten

syncBlocklist / BlocklistSync laden die Liste einmal herunter und wenden dann nur das an, was sich geändert hat.

Die Liste wird mit der genauen Position im Änderungsfeed geliefert, an der sie erstellt wurde, in einem x-cursor-Header und einem # cursor:-Kommentar. Die Clients lesen sie und setzen von dort fort, sodass es keine Lücke zwischen dem Snapshot und der ersten Abfrage gibt und keine Abhängigkeit davon, dass deine Uhr mit der des Servers synchron ist. Abfragen pro Sekunde können eine Position innerhalb einer Sekunde nicht ausdrücken, und eine Crawl-Batch schreibt Dutzende Ereignisse in eine, sodass eine Fortsetzung mit Sekundengranularität den Rest davon fallen lassen kann: Live gemessen, stellte die Fortsetzung nach dem ersten von drei Änderungen in derselben Sekunde beide Geschwister per Cursor wieder her und keines per Sekunde.

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() wendet nur robots-Übergänge auf die Liste an, weil die Liste daraus besteht. Edge-Ablehnungen, neue Preise und llms.txt-Änderungen kommen in other zurück, damit du separat darauf reagieren kannst – eine frühere Version löschte diese Domains aus der Deny-Liste, sodass ein Crawler genau das wieder abrief, was gerade begonnen hatte, ihn abzulehnen.

Urteile

Die maßgebliche Definition jedes Urteils – was es bedeutet, was es einen Crawler zu tun verpflichtet und ob erneutes Fragen es ändern könnte – ist als Daten unter /api/v1/verdicts veröffentlicht. Die Liste unten ist eine Zusammenfassung; falls die beiden jemals abweichen, hat der Endpunkt recht und diese Datei ist veraltet.

politeFetch überspringt standardmäßig disallow, refuse und pay, was die abgeleitete do_not_fetch-Menge des Endpunkts ist. Die Kopie hier ist bewusst – eine Crawl-Schleife sollte keinen Netzwerkaufruf benötigen, um zu entscheiden – und ein Test vergleicht die beiden, sodass sie nicht unbemerkt abweichen kann.

onPay: "fetch" (on_pay="fetch") überschreibt die Paywall-Standardeinstellung. Es ist ein explizites Opt-in und wird im Ergebnis als paidRouteOverridden aufgezeichnet, sodass es in deinen Logs erscheint.

Es degradiert, es scheitert nicht

Wenn die Volkszählung nicht erreichbar ist, wird jedes Urteil zu unknown und dein Crawl läuft wie gewohnt weiter. Ein Ausfall eines Drittanbieters darf deine Pipeline niemals stoppen. Es gibt einen Live-Test genau dafür.

Was wir über deinen Agenten veröffentlichen

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

Wenn eine Zahl falsch ist, ist der Korrekturkanal in dieser Antwort und auf deiner Betreiberseite. Registry-Fakten werden ohne Argument korrigiert; umstrittene Messungen werden zusammen mit dem Streit und den zugrunde liegenden Scan-Datensätzen veröffentlicht, statt stillschweigend geändert zu werden.

Grenzen

25 Domains pro Preflight-Aufruf anonym, 200 mit einem Pro-Schlüssel, 1.000 mit einem Data-Schlüssel. Übergib apiKey. Details unter https://crawlcensus.com/for-crawlers.

Tests

node test.mjs läuft absichtlich gegen die Live-Volkszählung. Der Wert dieses Clients liegt darin, ob seine Urteile der Realität entsprechen, und ein gemockter Test würde nur behaupten, dass der Mock mit sich selbst übereinstimmt.

MIT. Daten sind CC BY 4.0, Attribution als "Quelle: Crawl Census (crawlcensus.com)".