commoncrawl_check.py

Script Python per interrogare l'indice CDX di Common Crawl e misurare quante volte un URL o un dominio sono stati scansionati, crawl per crawl, nel tempo.

È lo stesso tipo di analisi usata da alcune inchieste giornalistiche (es. Drop Site News, luglio 2026) per misurare quanto intensamente una rete di siti viene "raccolta" dai crawler di Common Crawl.

A cosa serve Common Crawl

Common Crawl esiste dal 2007-2008 (fondato da Gil Elbaz), quindi ben prima dell'era dei modelli linguistici moderni. I suoi usi principali, nei primi 8-10 anni, erano piuttosto diversi da oggi:

Ricerca accademica su web e linguaggio

• Costruzione di corpora testuali per la linguistica computazionale e la ricerca su modelli statistici del linguaggio (n-grammi), prima che si parlasse di "LLM" in senso moderno
• GloVe, uno dei principali metodi di word embedding (2014, Stanford), è stato addestrato anche su un dump di Common Crawl: è uno degli usi più citati dell'epoca pre-transformer
• Progetti di traduzione automatica, come ParaCrawl (metà anni 2010), che minavano Common Crawl per estrarre coppie di frasi parallele in lingue diverse da usare per addestrare sistemi di traduzione

Motori di ricerca e SEO

• Startup che volevano costruire un motore di ricerca alternativo senza il costo di gestire un proprio crawler: Common Crawl abbassava drasticamente la barriera d'ingresso. Blekko, un motore di ricerca ormai chiuso, contribuì anzi dati al progetto
• Strumenti e ricerche SEO/di analisi del link graph (backlink, struttura dei collegamenti tra siti)

Didattica e big data

• Common Crawl era (ed è ancora) un dataset da manuale per insegnare Hadoop, Spark e l'elaborazione distribuita: è enorme, pubblico, gratuito, e ospitato su S3 in un formato pensato apposta per elaborazione parallela (WARC)

Ricerca su web e società

• Studio della struttura del web, diffusione di spam, diversità dei contenuti, analisi di rete su scala del web intero — ricerca accademica di web science, non legata al linguaggio

In sostanza: prima dei LLM, Common Crawl era soprattutto uno strumento per chi faceva ricerca (accademica o di startup) su scala web senza le risorse di Google o Microsoft per crawlare tutto da zero, più un dataset didattico per il big data. È diventato "l'infrastruttura invisibile dell'addestramento AI" solo con l'arrivo dei modelli su larga scala a partire dalla fine degli anni 2010, quando quello stesso dataset gratuito si è rivelato la base ideale (e più o meno l'unica disponibile su quella scala) per addestrare i primi grandi modelli linguistici.

Common Crawl è quindi un archivio pubblico e gratuito del web, aggiornato con un nuovo crawl al mese. Non è un motore di ricerca né un servizio RAG in sé: è il dataset grezzo a monte, che poi viene riusato per scopi diversi, tra cui:

• Addestramento di modelli linguistici: è una delle fonti testuali più usate al mondo per pre-training di LLM (spesso filtrata/derivata, es. i dataset C4 o RedPajama partono da Common Crawl).
• Corpora per RAG / retrieval: alcuni sistemi di retrieval-augmented generation indicizzano sottoinsiemi di Common Crawl come fonte di documenti da recuperare, invece di ricrawlare il web da zero.
• Ricerca accademica e giornalistica: analisi su larga scala del web (link graph, tracking SEO, disinformazione, monitoraggio di reti di siti) — è il caso d'uso di questo script: capire se e quanto spesso un dominio viene raccolto, non cosa i crawler ne fanno a valle.

Questo script si limita a interrogare l'indice CDX (metadati delle catture), non dice se e come un sito specifico venga effettivamente usato per addestrare un modello o alimentare un sistema RAG.

Cosa fa

1. Scarica l'elenco di tutti i crawl disponibili da https://index.commoncrawl.org/collinfo.json (Common Crawl pubblica circa un nuovo crawl al mese, es. CC-MAIN-2026-30).
2. Per ciascun crawl nel periodo richiesto, interroga il relativo indice CDX (https://index.commoncrawl.org/<crawl-id>-index) con l'URL o il dominio indicato.
3. Conta il numero di "catture" (righe di risultato = singole scansioni di quella pagina in quel crawl) e le somma per crawl.
4. Stampa un report leggibile in terminale e, opzionalmente, salva i dati grezzi in JSON.

Lo script non scarica il contenuto delle pagine, solo i metadati dell'indice: è quindi leggero anche su domini con molte pagine.

Requisiti

• Python 3.10 o superiore (lo script usa la sintassi str | None per i type hint)
• Nessuna dipendenza esterna: usa solo la libreria standard (urllib, json, argparse)

Uso

# Tutte le pagine di un dominio, su tutti i crawl disponibili
python3 commoncrawl_check.py example.org

# Un dominio, ristretto a un periodo (formato YYYY-MM)
python3 commoncrawl_check.py example.org --since 2026-01 --until 2026-09

# Un singolo URL esatto, invece che l'intero dominio
python3 commoncrawl_check.py https://example.org/chi-siamo/ --match exact

# Solo un sottopercorso del sito
python3 commoncrawl_check.py example.org/disarmo/ --match prefix

# Salvare anche i dati grezzi in JSON, oltre al report a schermo
python3 commoncrawl_check.py example.org --json risultati.json

# Forzare il ri-controllo di tutti i crawl, ignorando la cache locale
python3 commoncrawl_check.py example.org --refresh

# Cartella di cache diversa, o disabilitarla del tutto
python3 commoncrawl_check.py example.org --cache-dir /percorso/cache
python3 commoncrawl_check.py example.org --no-cache

Opzioni

Opzione	Default	Descrizione
url	(obbligatorio)	URL o dominio da controllare
--match	domain	Tipo di corrispondenza CDX: exact, prefix, host, domain
--since	(nessuno)	Mese di inizio, formato YYYY-MM
--until	(nessuno)	Mese di fine, formato YYYY-MM
--delay	1.0	Secondi di pausa tra una richiesta e l'altra
--json	(nessuno)	Percorso di un file dove salvare i risultati grezzi in JSON
--cache-dir	./commoncrawl_cache	Cartella della cache locale
--no-cache	(off)	Non legge né scrive la cache: sempre query live
--refresh	(off)	Ignora la cache in lettura e ri-interroga tutti i crawl (la aggiorna comunque)

--match domain include anche eventuali sottodomini; --match prefix prende tutte le pagine sotto un certo percorso; --match exact cerca solo quell'URL preciso, senza variazioni.

Cache locale

Ogni crawl di Common Crawl, una volta pubblicato, è immutabile: il numero di catture per un URL/dominio in CC-MAIN-2026-25, ad esempio, non cambierà mai più. Lo script sfrutta questo fatto per non ri-interrogare crawl già controllati in esecuzioni precedenti.

• Per ogni combinazione di URL/dominio + --match viene creato un file JSON in commoncrawl_cache/ (es. commoncrawl_cache/example.org_domain.json), con il numero di catture già noto per ciascun crawl_id.
• Ad ogni esecuzione, i crawl già presenti in cache non generano nessuna richiesta di rete (né la relativa pausa --delay); solo i crawl nuovi (es. quello del mese corrente, se non ancora controllato) vengono interrogati e poi salvati in cache.
• Il report indica (cache) accanto alle righe lette dalla cache, e alla fine mostra quanti crawl su quanti sono stati riusati.
• --refresh forza il ri-controllo di tutti i crawl nel periodo richiesto (utile se si sospetta un dato corrotto), aggiornando comunque la cache.
• --no-cache disabilita completamente la cache (né lettura né scrittura).

I file di cache sono testo semplice, ispezionabili e versionabili se utile; di norma però conviene tenerli fuori da git (dati derivati, non sorgenti).

Note operative

• Ritmo delle richieste: l'infrastruttura di Common Crawl è gratuita e mantenuta da una organizzazione no-profit. Lo script di default aspetta 1 secondo tra una richiesta e l'altra (--delay 1.0); non abbassarlo senza un buon motivo.
• Errori temporanei: un 503 o 429 viene ritentato automaticamente con backoff crescente. Un 404 viene invece interpretato correttamente come "nessuna cattura per quell'URL in quel crawl", non come errore.
• Domini con molte pagine: ogni richiesta scarica l'intero elenco delle catture di quel crawl per l'URL/dominio richiesto. Per siti molto grandi può valere la pena restringere il periodo con --since/--until invece di interrogare tutta la storia disponibile.
• User-Agent: lo script si identifica con uno User-Agent descrittivo (commoncrawl-check-script/1.0); è buona pratica personalizzarlo con un riferimento al proprio progetto/organizzazione prima di un uso intensivo.

Addendum: diritti degli autori dei contenuti

Common Crawl è una no-profit e non rivendica la proprietà dei contenuti che raccoglie: il copyright resta agli autori/editori originali. La sua posizione storica, però, lascia poco margine di controllo a chi pubblica contenuti:

• robots.txt come unico meccanismo di opt-out. Il crawler di Common Crawl (CCBot) rispetta robots.txt: un sito che blocca CCBot non verrà incluso nei crawl futuri. Common Crawl storicamente non ha offerto una procedura di rimozione dei contenuti già raccolti.
• Il problema strutturale: robots.txt è nato per controllare l'indicizzazione nei motori di ricerca, non per esprimere un consenso specifico all'addestramento di modelli linguistici. È una scelta "tutto o niente": non permette a un editore di restare indicizzato da Google ma escludersi dai dataset di training.
• Bloccare CCBot oggi non ha effetto retroattivo. I crawl già pubblicati (e già scaricati da terzi per costruire dataset derivati come C4 o RedPajama) restano in circolazione: Common Crawl non può far sparire copie già distribuite ad altri.

Aggiornamento 2026: la tensione tra Common Crawl e gli editori è degenerata in azioni legali formali:

• 29 aprile 2026 — la News/Media Alliance ha inviato a Common Crawl una lettera di diffida formale chiedendo: la rimozione dei contenuti degli editori su richiesta, una dichiarazione pubblica che l'organizzazione non possiede né autorizza l'uso dei contenuti raccolti, una revisione dei termini d'uso che vieti esplicitamente l'addestramento di modelli AI, e avvisi vincolanti nel registro di opt-out.
• 3 giugno 2026 — Digital Content Next ha inviato una diffida per conto di AP, New York Times, NBC, Bloomberg, NPR e Fox, chiedendo a Common Crawl di interrompere la raccolta dei loro contenuti protetti e di rimuoverli dai dataset già usati per addestrare modelli AI.

A metà 2026 si tratta ancora di richieste in corso, non di una policy formalmente adottata da Common Crawl né di cause legali depositate: il formato stesso dell'archivio rende la cancellazione strutturalmente lenta, e bloccare CCBot oggi non incide su ciò che è già stato raccolto in passato.

Questo script serve proprio a misurare quanto un dominio viene raccolto — utile a un editore che voglia capire la propria esposizione, ma non implica nulla su come quei dati vengano poi effettivamente usati a valle.