Come si usa l'API di Google Search Console?

Q: Come si usa l'API di Google Search Console?

Crea un progetto Cloud, abilita l'API, autorizza l'accesso con OAuth, poi interroga i dati sulle prestazioni, l'ispezione degli URL e le sitemap. Ecco i passaggi e le quote.

Crea un progetto nella console Google Cloud, abilita la Google Search Console API, crea le credenziali OAuth 2.0 e accedi con un account Google che abbia accesso alla proprietà. A quel punto puoi inviare richieste a quattro risorse: Search Analytics per clic, impressioni, CTR e posizione; URL Inspection per lo stato di indicizzazione; Sitemaps; e Sites. Le sole chiavi API non bastano: ogni chiamata richiede un token OAuth, e le quote limitano la quantità di dati che puoi richiedere.

Cosa copre l'API e cosa no

Risorsa	Metodi	A cosa serve
Search Analytics	`query`	Righe di prestazioni per query, pagina, paese, dispositivo, aspetto nella ricerca, data od ora
URL Inspection	`index.inspect`	La versione indicizzata di un singolo URL: copertura, ultima scansione, canonical
Sitemaps	`list`, `get`, `submit`, `delete`	Gestione delle sitemap inviate da una proprietà
Sites	`list`, `get`, `add`, `delete`	Le proprietà dell'account con cui hai effettuato l'accesso

Questa è l'intera API. Link, Statistiche di scansione, il report Indicizzazione delle pagine e il report Core Web Vitals non hanno alcun endpoint, quindi restano disponibili solo nell'interfaccia di Search Console. URL Inspection mostra ciò che è presente nell'indice di Google, non un test in tempo reale della pagina.

Configurare l'accesso

Nella console Google Cloud, crea o scegli un progetto.
Abilita la Google Search Console API per quel progetto.
Configura la schermata di consenso OAuth e crea un ID client OAuth.
Richiedi uno scope: https://www.googleapis.com/auth/webmasters.readonly per la sola lettura, oppure https://www.googleapis.com/auth/webmasters se vuoi anche inviare o eliminare sitemap.
Accedi con un account che abbia le autorizzazioni sulla proprietà. Per leggere i dati sulle prestazioni serve almeno l'accesso in lettura; l'API vede esattamente ciò che vede quell'account.

La tua prima query a Search Analytics

POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "startDate": "2026-09-01",
  "endDate": "2026-09-30",
  "dimensions": ["query", "page"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

Il sito va indicato nel percorso, con codifica URL: sc-domain:example.com per una proprietà di dominio, oppure il prefisso esatto con la barra finale, ad esempio https://www.example.com/, per una proprietà con prefisso URL. I campi più importanti:

Le date sono inclusive e riferite al fuso orario del Pacifico.
type è web per impostazione predefinita; gli altri valori sono image, video, news, googleNews e discover. Ognuno richiede una richiesta separata.
I filtri vanno in dimensionFilterGroups, con operatori che vanno da equals e contains a includingRegex e excludingRegex (sintassi RE2).
rowLimit va da 1 a 25.000 (valore predefinito 1.000); startRow scorre le righe successive.
dataState è final per impostazione predefinita; all aggiunge i giorni più recenti non ancora definitivi, mentre hourly_all funziona con la dimensione hour.

Ogni riga restituisce keys, clicks, impressions, ctr (da 0 a 1) e position, ordinate per clic a meno che tu non raggruppi per data.

I limiti che condizionano il tuo codice

50.000 righe al giorno per tipo di ricerca. Scorri i risultati con startRow a blocchi di 25.000 e fermati quando la risposta è vuota. Per ottenere il massimo, interroga un giorno alla volta.
Quota di carico. Raggruppare o filtrare contemporaneamente per pagina e query è la richiesta più costosa, e gli intervalli di date lunghi costano più di quelli brevi. Se superi la quota a breve termine, Google ti chiede di attendere 15 minuti.
Frequenza delle richieste. 1.200 query al minuto per sito e per utente; 40.000 al minuto e 30.000.000 al giorno per progetto.
Quota di URL Inspection. 2.000 ispezioni al giorno e 600 al minuto per ogni proprietà.
16 mesi di storico, e i dati sono in genere disponibili due o tre giorni dopo la fine della giornata.
Le righe non corrispondono ai totali. Le query rare vengono escluse dalle righe a livello di query, e il raggruppamento per pagina conta le impressioni in modo diverso dal raggruppamento per proprietà, quindi leggi i totali da una richiesta senza la dimensione query.

Errori comuni

Usare http:// quando la proprietà è https://, oppure omettere la barra finale, genera un errore di autorizzazione anche quando l'account ha accesso.
In URL Inspection, richiedere un URL esterno alla proprietà viene rifiutato: l'URL deve trovarsi sotto il siteUrl che passi.
Un mese raggruppato per query e pagina in una sola chiamata restituisce solo le righe principali. Le richieste giornaliere ne restituiscono di più.

Come ti aiuta AutoPSEO

Se preferisci non gestire OAuth e la paginazione, AutoPSEO si collega tramite l'accesso con Google ed espone gli stessi dati attraverso la propria REST API su /v1 (con un documento OpenAPI 3.1) e un server MCP, autorizzati da una chiave API disponibile in Account → API keys. Sono disponibili chiavi di sola lettura, l'endpoint di search analytics restituisce fino a 5.000 righe per chiamata, e gli strumenti di URL Inspection dell'app tengono il conto per te della quota di 2.000 al giorno di Google. Consulta MCP e chiavi API. Per conservare i dati oltre i 16 mesi senza scrivere una pipeline, leggi per quanto tempo Search Console conserva i dati.

Fonti: Google, riferimento API, metodo query di Search Analytics, limiti di utilizzo, come ottenere tutti i tuoi dati e guida all'autorizzazione.