API di Search Console: come ottenere l'accesso e cosa restituisce

L'API di Search Console è l'interfaccia programmatica di Google agli stessi dati che vedi in Google Search Console: clic, impressioni, posizione e stato dell'indicizzazione, forniti tramite codice invece che dalla dashboard. Per usarla, abilita l'API in Google Cloud Console, crea le credenziali e poi autorizzale su una proprietà di cui sei già titolare in Search Console.

Prima di costruire qualcosa di personalizzato, verifica se ti serve davvero l'accesso diretto all'API. La funzione site traffic di SearchBlueprint riunisce già in un'unica vista i tuoi dati di Search Console, Google Analytics e le visite dei crawler AI, e per la maggior parte dei proprietari di siti risponde alla domanda "cosa sta succedendo con i miei clic e le mie impressioni" senza scrivere una riga di codice.

Cosa fa l'API di Search Console

È un'API REST pubblicata da Google che rispecchia gran parte della dashboard di Search Console: rendimento nella ricerca (query, pagine, paesi, dispositivi), stato delle sitemap e risultati dell'ispezione URL. La chiami da uno script, da un servizio backend o da uno strumento, e restituisce JSON strutturato invece di una schermata da leggere a mano.

Non ti dà nulla che Search Console non mostri già. Cambiano il volume e l'automazione: puoi estrarre anni di dati, combinare più proprietà o aggiornare un report ogni mattina senza che nessuno apra una scheda del browser.

Come ottenere l'accesso: chiave API, OAuth e abilitazione dell'API

Una semplice chiave API non basta. Gli endpoint di Search Analytics di Google richiedono un utente o un account di servizio autorizzato sulla specifica proprietà, perché i dati sono legati a chi ha verificato la titolarità. La sequenza qui sotto segue la console attuale.

Passaggio 1: abilita l'API in Google Cloud Console

Vai su Google Cloud Console, seleziona o crea un progetto, apri il menu APIs & Services, poi Library. Cerca "Google Search Console API", cliccaci sopra e clicca su Enable.

Passaggio 2: crea le credenziali

Sempre in APIs & Services, apri Credentials, poi Create Credentials. Per script e job da server a server, scegli un Service Account e scarica la sua chiave JSON. Per un'app che agisce per conto di un utente che ha effettuato l'accesso, scegli invece un OAuth client ID.

Passaggio 3: concedi l'accesso in Search Console

L'API vede solo le proprietà a cui l'identità autenticata ha accesso. Se hai creato un account di servizio, copia il suo indirizzo email e aggiungilo come utente in Settings > Users and permissions. L'accesso completo (Full) o limitato (Restricted) è il minimo, e quello giusto dipende dal fatto che l'account debba inviare sitemap o solo leggere i dati.

Passaggio 4: fai la tua prima chiamata

Con le credenziali in mano, autenticati e chiama il metodo query di Search Analytics, passando una data di inizio, una data di fine e le dimensioni che vuoi (query, page, country, device). Un problema di verifica tende a emergere proprio qui. Se l'account di servizio non vede la proprietà, probabilmente va riesaminata la verifica stessa in Search Console, ed è meglio sistemarla alla fonte prima di fare il debug della chiamata API.

Cosa puoi estrarre: gli endpoint in sintesi

Endpoint	Cosa restituisce	Uso tipico
Search Analytics query	Clic, impressioni, CTR, posizione per query/pagina/paese/dispositivo	Dashboard di posizionamento e traffico
Sitemaps	Elenca, invia o elimina voci di sitemap	Reinvio automatico della sitemap dopo una ricostruzione
URL Inspection	Stato dell'indicizzazione, canonical, usabilità su mobile per un singolo URL	Verificare se una pagina è stata indicizzata dopo la pubblicazione
Sites	Elenca o aggiunge le proprietà a cui l'account ha accesso	Strumenti per agenzie con più siti

API di Search Console vs. esportazione manuale vs. strumenti no-code

Opzione	Ideale per	Impegno di configurazione	Limite principale
Esportazione dalla UI di Search Console	Un singolo controllo occasionale	Nessuno	Righe limitate, nessuna programmazione, nessuna automazione
Chiamate API dirette	Dashboard personalizzate, sviluppatori	Da medio ad alto (OAuth, codice)	Devi mantenere tu l'autenticazione e il codice
Wrapper API no-code	Chi non è sviluppatore ma ha comunque bisogno di JSON	Basso	Canone mensile, meno controllo sui campi
Piattaforme di integrazione (iPaaS)	Prodotti SaaS che integrano i dati di GSC per i propri clienti	Medio	Pensate per i fornitori, non per il reporting di un singolo sito

I wrapper no-code esistono per saltare il lavoro su OAuth e sugli endpoint. Il connettore Search Console di NoCodeAPI, per esempio, trasforma le chiamate a Search Analytics e alle sitemap in un unico endpoint JSON autenticato. Fornitori come Paragon propongono integrazioni native con Search Console realizzate con circa il 70% di impegno ingegneristico in meno rispetto a scrivere da zero la logica di OAuth e sincronizzazione, ma sono rivolte ai team SaaS che distribuiscono i dati di Search Console all'interno del proprio prodotto, non a chi vuole solo i propri numeri.

Quando bastano gli strumenti gratuiti e quando no

L'interfaccia di Search Console basta per controllare un singolo URL, rispondere a una domanda una tantum come se una pagina è stata indicizzata, o dare un'occhiata alle query principali del mese scorso. Non è fatta per niente di ricorrente né distribuito su molte proprietà.

L'API, o uno strumento costruito su di essa, si ripaga quando ti servono:

• Un report programmato che si aggiorna senza che nessuno apra Search Console
• Dati su più proprietà di quante potresti scorrere a mano tra le schede
• Uno storico oltre quello che la UI mostra comodamente
• Dati di ricerca uniti ad altre fonti

Se scegli la strada dei dati uniti, conviene conoscere la vera differenza tra Search Console e Analytics, perché rispondono a domande diverse e nessuna delle due sostituisce l'altra.

Errori comuni

• Usare una chiave API al posto di OAuth o di un account di servizio. Le chiamate a Search Analytics falliscono senza un'autorizzazione corretta, per quanto valida sembri la chiave.
• Dimenticare di aggiungere l'account di servizio come utente in Search Console. La credenziale API e il permesso sulla proprietà sono due passaggi separati.
• Pensare che l'API restituisca più storico della UI. Entrambe attingono agli stessi dati, quindi il vantaggio dell'API è l'automazione e non mesi di dati in più.
• Fissare nel codice intervalli di date e dimensioni. Le query che non gestiscono correttamente la paginazione troncano i risultati senza avvisare sui siti ad alto traffico.

Domande frequenti

Devo pagare per l'API di Search Console?

No. L'API è gratuita entro i normali limiti di quota di Google, e paghi solo se costruisci o acquisti uno strumento basato su di essa.

Che differenza c'è tra una chiave API e OAuth per Search Console?

Una chiave API identifica un progetto. OAuth o un account di servizio identificano e autorizzano un utente o un account specifico su una proprietà, e i dati di Search Analytics richiedono questi ultimi.

Posso usare l'API di Search Console senza programmare?

Sì, tramite connettori no-code che racchiudono l'API in un endpoint JSON più semplice. Dovrai comunque autenticarti con Google e gestire un account presso quel fornitore.

Quanti dati posso estrarre per ogni richiesta?

La documentazione di Google descrive i limiti di righe e di quota per ogni metodo. Gli account di grandi dimensioni di solito devono paginare le richieste invece di estrarre tutto in una sola chiamata.

L'API funziona per le proprietà che non ho verificato?

No. L'accesso è legato alla titolarità verificata in Search Console, quindi la credenziale che usi deve prima essere aggiunta come utente su quella proprietà.

Per il riferimento tecnico completo, comprese quote e parametri dei metodi, consulta la documentazione dell'API di Search Console di Google.

Check your numbers before you build anything

Se l'obiettivo è avere visibilità su clic, impressioni e su come i crawler AI trattano le tue pagine, l'API di Search Console non è necessaria. Salta la configurazione di OAuth e guarda gli stessi dati riuniti nella vista site traffic di SearchBlueprint. Per uno sguardo più ampio su come il tuo sito si comporta oggi nella ricerca, parla con il team, che ti fornirà un report di esempio costruito sui dati del tuo sito.

Risorse / Riferimenti

1. Documentazione dell'API di Search Console

Fonti

• Build a native Google Search Console integration - Paragon
• How do I enable the new Google Search Console (formerly ...
• Google Search Console Developers Training Guide
• Google Search Console JSON API to Read and Write
• Google Search Console API | Indexing & Search Analytics

I left one heading in English by mistake. The heading "Check your numbers before you build anything" should read "Controlla i tuoi numeri prima di costruire qualsiasi cosa".