Search Console API e BigQuery: i dati oltre le 1.000 righe

Estrarre i dati di Search Console è comodo finché te ne bastano mille righe. La scena la conosci: devi capire cosa è successo a una pagina fra marzo e giugno, apri il rapporto Rendimento, metti il filtro, scorri la tabella delle query e a un certo punto finisce. Mille righe. Sotto c’è il resto della coda lunga, cioè la parte dove si vede se hai perso click su cento ricerche piccole o su una grossa.

Non è un bug e non è il tuo account: è il limite dichiarato dello strumento. Da lì in avanti ci sono due strade, la Search Console API e il bulk data export su BigQuery, e fanno due lavori diversi. Quale serve quando, cosa dice la documentazione ufficiale su ciascuna, e perché una delle due va attivata oggi anche se i dati ti serviranno fra sei mesi.

⚠️ Perché la tabella si ferma a 1.000 righe

Vale la pena leggere cosa scrive Google, perché il limite non è solo di visualizzazione. Nella pagina About Search Console data c’è la frase che chiude il discorso: “Our tables can show a maximum of 1,000 rows, so some rows might be omitted. You can see a larger selection of table rows using the Search Console API”. Ed è Google stessa a indicare l’API come via d’uscita.

Il download non ti salva: la pagina sull’esportazione dai rapporti dice che “Data is truncated to 1,000 rows of representative examples of your data”. Rappresentativi, non tutti.

C’è poi un secondo taglio, meno noto e più importante da spiegare a un cliente: “Due to internal limitations, Search Console stores top data rows and not all data rows”, sempre nella stessa pagina. Search Console conserva le righe principali e omette le query rare per tutela della privacy. Quindi una parte della coda lunga non è nascosta dietro il limite di visualizzazione: non esiste proprio nell’archivio. È il motivo per cui i totali del grafico non tornano mai con la somma della tabella, e non è colpa tua.

Ultimo vincolo, quello che rende urgente il resto dell’articolo: lo storico è di 16 mesi. La frase più esplicita, curiosamente, sta nella documentazione di Analytics: “Search Console keeps data for the last 16 months” (fonte). Tutto quello che non porti fuori entro sedici mesi non lo recuperi più.

📊 I tre livelli di accesso, messi in fila

Letta così la scelta è meno ideologica di come viene raccontata: l’API è il modo di prendere quello che Search Console ha già; il bulk export è il modo di non perdere quello che avrà domani. Le due cose non si escludono, anzi si usano insieme - l’API per recuperare i 16 mesi che hai adesso, l’export per accumulare da qui in avanti.

✅ Search Console API: 25.000 righe per richiesta, e la paginazione

Il metodo che serve è uno solo, searchanalytics.query. La documentazione del metodo è precisa sui numeri: rowLimit ha “Valid range is 1-25,000; Default is 1,000”, e startRow è “Zero-based index of the first row in the response”. Tradotto: 25.000 righe alla volta, e per andare oltre si sposta l’offset di 25.000 e si richiede. La guida ufficiale alle query lo dice come metodo consigliato per i dataset che superano quella soglia.

Le dimensioni disponibili sono country, device, page, query, searchAppearance, date e hour. Due parametri che di solito nessuno tocca e che invece cambiano il risultato: aggregationType, che decide se aggregare per proprietà o per pagina (byPage), e dataState, che con il valore all include anche i dati freschi non ancora consolidati, mentre l’impostazione predefinita restituisce solo dati finali.

Sulle quote nessun allarme per un sito PMI: la pagina dei limiti indica 1.200 query al minuto per sito e per utente sulla Search Analytics, e un’estrazione di 16 mesi ci sta dentro comodamente.

🛠️ Google Search Console API con Python: la query minima

Non serve un tutorial fiume, servono venti righe oneste. Con la libreria client ufficiale, autenticato con le tue credenziali, il ciclo di paginazione è tutto qui:

from googleapiclient.discovery import build

service = build('searchconsole', 'v1', credentials=creds)
site = 'sc-domain:esempio.it'
rows, start = [], 0

while True:
    resp = service.searchanalytics().query(siteUrl=site, body={
        'startDate': '2026-01-01',
        'endDate': '2026-06-30',
        'dimensions': ['date', 'query', 'page'],
        'rowLimit': 25000,
        'startRow': start,
    }).execute()
    batch = resp.get('rows', [])
    rows += batch
    if len(batch) < 25000:
        break
    start += 25000

Il pezzo che conta è la condizione di uscita: si smette quando il lotto torna più corto del limite richiesto, non a un numero deciso a occhio. Il resto - autenticazione OAuth o service account, salvataggio in CSV o in un foglio - è idraulica, e la doc di Google la copre meglio di qualsiasi articolo italiano.

Una nota pratica: chiedere date, query e page insieme produce una riga per ogni combinazione e il conteggio esplode. Se ti serve il confronto per pagina chiedi page e date, se ti serve la coda delle ricerche chiedi query e date. Una domanda per volta, come con qualsiasi database.

Bulk data export: cosa arriva davvero dentro BigQuery

Qui cambia la natura del dato. Esportare i dati di Search Console con il bulk export non vuol dire chiamare una API: è un flusso che Search Console scrive da sola nel tuo progetto BigQuery, una volta al giorno, finché non lo spegni. La pagina About bulk data export definisce il perimetro con una frase sola: “you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries”. Tutto quello che Search Console ha, tranne le query anonimizzate.

Le tabelle sono tre, elencate nella reference ufficiale:

• searchdata_site_impression: dati aggregati per proprietà, con data_date, query, country, search_type, device, impressions, clicks e sum_top_position.
• searchdata_url_impression: la stessa cosa aggregata per URL, quindi con il campo url, più una serie di booleani is_[search_appearance_type] per i rich result.
• ExportLog: il registro degli export riusciti, utile solo quando qualcosa non torna.

Due dettagli che evitano il primo errore di lettura. La posizione media non è una colonna: si calcola con la formula della doc, SUM(sum_top_position)/SUM(impressions) + 1, perché il campo è a base zero. E i dati arrivano in modo incrementale, con chiavi ripetute: Google scrive esplicitamente che “you should almost always aggregate all your metrics”. Chi legge una riga singola come fosse un totale legge un numero sbagliato.

Il valore vero è la granularità: una riga per giorno, query, URL, paese e dispositivo. Nessun taglio a 1.000 righe e nessuna scelta, fatta da altri, di quale parte della tabella mostrarti: resta il perimetro di quello che Search Console conserva. Le query anonimizzate restano fuori anche qui, e va detto sempre: non esiste un livello di accesso in cui tornano.

L’interfaccia ti dà una fotografia già ritagliata. Il bulk export ti dà i negativi. Con i negativi puoi rifare qualsiasi inquadratura ti serva fra un anno, anche una che oggi non ti viene in mente.

⚠️ Non è retroattivo: ogni giorno che passa è storico perso

Questo è il punto per cui vale la pena leggere fin qui. La pagina Start a new bulk data export lo dice in due frasi che messe insieme non lasciano scampo: “The first export will happen up to 48 hours after your successful configuration in Search Console. The first export includes data for the day of the export”, e poco sotto “If you want to see historical data that precedes your initial setup, use the Search Console API or the reports”.

Il primo export contiene il giorno dell’export. Non il mese prima, non l’anno prima. Se lo accendi oggi il tuo archivio grezzo parte da oggi; se lo accendi a marzo hai perso otto mesi di righe che nessuno ti restituisce, perché intanto la finestra dei 16 mesi scorre e mangia la coda.

È lo stesso ragionamento che ho già fatto per le proprietà social di Search Console: collegarle adesso costa mezz’ora, non collegarle costa uno storico. Qui la posta è più alta, perché non parliamo di un report in più ma della sola copia grezza e giornaliera dei tuoi dati di ricerca.

Trasparenza sul mio stato: l’export sul mio sito e sulle proprietà dei clienti che gestisco lo sto attivando in queste settimane, quindi non ho ancora un anno di righe grezze da mostrare. Posso dire cosa mi ha convinto ad attivarlo, ed è scritto qui sopra in inglese, nella doc di Google.

Cosa serve: progetto Cloud, fatturazione, free tier

Il prerequisito che ferma il 90% delle attivazioni: un progetto Google Cloud con fatturazione valida. La doc è esplicita anche nell’elenco degli errori possibili, dove alla voce Missing billing information in Cloud project si legge che “The Cloud project must have a valid billing configuration, otherwise the write will fail (even if you granted permissions)” (fonte).

La sequenza, in ordine:

1. Progetto Cloud con fatturazione attiva, e dentro il progetto abilitare BigQuery API e BigQuery Storage API.
2. In IAM, dare accesso al service account search-console-data-export@system.gserviceaccount.com con i due ruoli BigQuery Job User e BigQuery Data Editor.
3. In Search Console, da Impostazioni > Esportazione di dati collettiva, incollare l’ID del progetto (non il numero), scegliere nome e regione del dataset. La regione poi non si cambia facilmente.
4. Aspettare fino a 48 ore il primo export. Serve essere proprietari della proprietà: gli utenti con permessi inferiori non vedono nemmeno la voce.

Sui costi la risposta onesta è che per una PMI il conto tende a zero, ma non è zero garantito. Il free tier di BigQuery, documentato da Google, è di 10 GiB di storage al mese e 1 TiB di dati analizzati dalle query al mese: i volumi di un sito aziendale italiano ci stanno dentro con margine largo. Google avvisa però che i dati si accumulano per sempre se non metti una scadenza sulle partizioni, e la doc pone il vincolo: almeno 14 giorni, e mai sulla tabella intera, altrimenti cancelli tutto.

Va detto chiaro perché conta in un preventivo: la carta di credito si collega comunque. Non perché si paghi, ma perché senza fatturazione la scrittura fallisce. È una frizione amministrativa, non un costo, e conviene spiegarla prima a un cliente che vede la parola “fatturazione” e si irrigidisce.

Cosa ci fai: il prima/dopo su una singola query

Il motivo per cui mi interessa questa infrastruttura non è collezionare righe. È che alla domanda che i clienti fanno davvero - “la mia pagina ha perso click perché c’è la risposta AI sopra?” - con la tabella dell’interfaccia non si risponde in modo serio. Anticipo subito il limite, che sta anche in fondo a questa sezione: nemmeno con i dati grezzi si arriva a una misura diretta dell’effetto AI, si arriva a un’inferenza fatta su segmenti invece che su medie.

Sulla pillar GEO ho già mostrato il punto: la forbice fra impressioni e click non si apre su tutto il sito insieme, si apre su alcuni tipi di pagina e non su altri, e chi guarda solo il totale non la vede. Per isolare quei segmenti servono le righe, non un rapporto già aggregato da qualcun altro: click e impressioni per singola query e singolo URL, giorno per giorno, sullo stesso intervallo dell’anno prima.

Con il dato grezzo diventano possibili tre cose che dall’interfaccia non riesci a fare:

• Il confronto per segmento. Raggruppare gli URL per tipo (schede, categorie, articoli, pagine marchio) e confrontare il rapporto click/impressioni fra due periodi. È l’analisi che separa “il sito va male” da “va male una famiglia di pagine”.
• La coda lunga vera. Contare quante query hanno perso click sotto la soglia in cui l’interfaccia le taglia. Spesso il calo non sta in dieci ricerche grosse, sta in quattrocento piccole.
• Il monitoraggio ripetibile. Una query salvata che rigiri ogni mese e ti dà lo stesso numero calcolato allo stesso modo. La riproducibilità è quello che distingue un report da uno screenshot.

Un limite da dichiarare, perché il sito non deve promettere quello che lo strumento non dà: nelle tabelle dell’export non c’è un campo documentato che marchi le impressioni dentro le AI Overviews. Il rapporto dedicato alle funzionalità di AI generativa, come ho scritto guardando cosa misura davvero Search Console su AI e social, oggi espone solo impressioni, senza click e senza query, ed è la stessa asimmetria da cui parte il confronto fra Bing AI e Google AI. Quindi il prima/dopo sull’effetto delle risposte AI resta un’inferenza fatta bene - posizioni stabili, impressioni che tengono, click che scendono su un segmento - non una misura diretta. E prima di attribuire un calo all’AI vanno escluse le cause tecniche, a partire dal rapporto Indicizzazione, come nella checklist dopo un Core Update.

Da dove partirei io

Se domani mattina dovessi mettere in ordine la misurazione di un sito PMI, l’ordine sarebbe questo: attivare il bulk export oggi, perché l’unico costo di aspettare è irreversibile; poi, con calma, usare l’API per portarsi a casa i 16 mesi che l’archivio ha ancora; infine tenere l’interfaccia per quello in cui è insuperabile, cioè guardare una cosa al volo e capire se vale la pena scavare.

È il lavoro di misurazione che faccio per i clienti prima di toccare qualsiasi contenuto: prima si mette in piedi il dato, poi si interviene, poi si rimisura sullo stesso metro. Se hai dubbi su cosa è successo al traffico negli ultimi mesi e nessuna voglia di litigare con service account e permessi IAM, scrivimi da uno dei canali qui sotto o dalla pagina contatti: l’attivazione si fa in una sessione, e da quel giorno lo storico inizia ad accumularsi per te.