Skip to content

Introduzione

Lo script gsc.py, presente nel repository evemilano/gsc_api, è uno strumento Python progettato per interagire con l’API di Google Search Console (GSC). Questo script permette di estrarre dati relativi alle prestazioni di un sito web, offrendo una visione dettagliata delle metriche più rilevanti per monitorare e ottimizzare le strategie SEO.

Ideato per semplificare il processo di analisi, questo script consente di automatizzare l’estrazione delle metriche di traffico organico dei siti web, come clic, impressioni, CTR e posizione media. Grazie alla sua struttura flessibile e alla compatibilità con Python, offre un punto di partenza potente per implementare flussi di lavoro personalizzati.

Con l’integrazione di librerie come pandas e il supporto diretto alle API di GSC, lo script permette di ottenere dati precisi in pochi minuti. Che si tratti di generare report dettagliati o di ottimizzare le strategie SEO, questo script rappresenta una soluzione versatile e professionale per consulenti, agenzie e sviluppatori.

Obiettivo dello script

Lo scopo principale dello script è offrire un metodo automatizzato per raccogliere e analizzare i dati di Google Search Console in modo preciso ed efficace. Attraverso l’utilizzo dell’API di GSC, questo strumento consente di accedere facilmente alle metriche necessarie per monitorare le performance SEO di un sito web e prendere decisioni informate. Le informazioni raccolte includono:

  • Click: il numero di clic che il sito riceve dai risultati di ricerca su Google, una metrica fondamentale per comprendere il coinvolgimento degli utenti.
  • Impressioni: il numero di volte in cui il sito appare nelle SERP di Google, utile per misurare la visibilità del sito rispetto a determinate query.
  • CTR (Click Through Rate): il rapporto tra clic e impressioni, che indica l’efficacia delle pagine web nel convertire la visibilità in clic.
  • Posizione media: la posizione media del sito nei risultati di ricerca per specifiche query, una metrica essenziale per valutare il posizionamento del sito nel tempo.

Queste metriche, combinate, offrono un quadro chiaro delle performance del sito e consentono di individuare opportunità di miglioramento, come ottimizzare contenuti specifici o identificare keyword con alto potenziale. Lo script rappresenta un supporto indispensabile per chi vuole massimizzare i risultati delle proprie attività SEO.

Funzionalità principali

  1. Autenticazione: Lo script utilizza credenziali di servizio JSON per autenticarsi con l’API di Google Search Console, garantendo un accesso sicuro e verificato. Questo approccio sfrutta un file di credenziali specifico generato tramite Google Cloud, che contiene informazioni essenziali come l’ID del client e la chiave privata necessarie per stabilire una connessione affidabile. Durante l’esecuzione dello script, il file JSON viene letto e utilizzato per generare un token di autenticazione, che consente di accedere ai dati del Search Console in conformità con le autorizzazioni assegnate al progetto. Questo meccanismo assicura che solo utenti autorizzati possano accedere ai dati, proteggendo così informazioni sensibili come le metriche del sito e le query di ricerca. È importante mantenere il file JSON in un ambiente sicuro e protetto per evitare accessi non autorizzati. Inoltre, lo script è stato progettato per segnalare eventuali problemi di autenticazione, come credenziali scadute o errate, fornendo messaggi di errore chiari per agevolare la risoluzione dei problemi.
  2. Estrazione dati per intervallo di date: Consente di recuperare dati su base temporale, specificando un intervallo di date. Va sottolineato che i dati forniti dall’API di Google Search Console non sono in tempo reale, ma presentano generalmente una latenza di 2-3 giorni. Questo significa che, ad esempio, i dati relativi alle performance di oggi non saranno disponibili immediatamente. Questa caratteristica richiede una pianificazione accurata delle analisi, poiché le decisioni basate sui dati dovranno tener conto di questo ritardo intrinseco.
  3. Limite di righe richieste: Nello script è presente il parametro rowLimit, che è impostato a 25000, ovvero il numero massimo di righe che l’API di Google Search Console consente di estrarre in una singola chiamata. Se questo limite non viene specificato, l’API restituisce solo le prime 1.000 righe per chiamata, un valore predefinito che potrebbe non essere sufficiente per analisi dettagliate su siti con grandi volumi di dati. Per forzare l’API a restituire fino a 25.000 righe, è necessario dichiarare esplicitamente il parametro nel codice, come avviene nello script. Questo approccio è fondamentale per evitare il rischio di perdere dati importanti e per garantire una copertura completa delle informazioni disponibili. Tuttavia, è importante notare che richiedere il massimo numero di righe può aumentare il tempo di risposta dell’API, specialmente per siti con molteplici dimensioni e filtri applicati.
  4. Filtraggio dei dati: È possibile filtrare i dati per query, pagina, paese, dispositivo e altri parametri supportati dall’API.
  5. Metriche e dimensioni supportate:
    • Metriche: clic, impressioni, CTR e posizione media.
    • Dimensioni: query di ricerca, pagine, paesi, dispositivi e date.
    • Per maggiori informazioni su come Google calcola le metriche ti consiglio di leggere questa documentazione.
  6. Output strutturato: I dati estratti possono essere formattati in un formato leggibile, come JSON o CSV, per ulteriori analisi. Lo script esporta i dati in un file Excel.
  7. Gestione degli errori: lo script include logiche per catturare e gestire errori comuni come problemi di autenticazione o limiti di richiesta API.

Aggregazione delle query in una tabella pivot

La fase finale dello script prevede l’utilizzo della funzione pivot_table di pandas per riorganizzare i dati estratti da Google Search Console. Questo processo consente di trasformare il DataFrame originale, che include informazioni dettagliate sulle query, in una struttura più sintetica e analitica. Le query vengono impostate come indici, mentre metriche come clic, impressioni, CTR e posizione media diventano colonne con valori aggregati. Questa trasformazione facilita l’analisi, offrendo una visione più chiara delle performance di ciascuna query.

Organizzare i dati in una tabella pivot consente di identificare rapidamente pattern, tendenze o anomalie, come le query che generano il maggior numero di clic o presentano un CTR elevato. Questa riorganizzazione riduce la complessità del DataFrame e agevola l’applicazione di ulteriori analisi statistiche, rendendo più semplice la generazione di report e la comunicazione dei risultati a stakeholder non tecnici.

Il pivoting permette di consolidare i dati raccolti giornalmente tramite chiamate API, eliminando la ridondanza causata dalla presenza della stessa query in più righe. Attraverso l’aggregazione, ogni query unica occupa una sola riga nel DataFrame finale, con metriche calcolate sull’intero periodo analizzato. Questo approccio fornisce una panoramica chiara delle performance complessive, semplificando l’identificazione di opportunità di ottimizzazione SEO.

La funzione pivot_table di pandas permette di specificare sia le colonne da aggregare sia le funzioni di aggregazione da applicare, come somme o medie. Questa tecnica non solo migliora l’efficienza computazionale, ma consente anche una più facile manipolazione dei dati, come filtraggio e ordinamento, rendendo il processo analitico più rapido e produttivo.

Perché conviene dividere il periodo e fare chiamate per ogni singolo giorno

Un lettore attento potrebbe chiedersi il motivo per cui si scelgono chiamate giornaliere invece di una singola chiamata per un periodo più lungo, come un mese. La risposta risiede nella necessità di massimizzare i dati ricevuti, soprattutto nel caso di siti di grandi dimensioni. L’API di Google Search Console ha dei limiti intrinseci nella quantità di dati che può restituire in una singola chiamata: anche utilizzando il parametro rowLimit impostato al massimo consentito di 25.000 righe, i dati ottenuti potrebbero essere parziali.

Quando si esegue una chiamata unica per un periodo esteso, come un mese, l’API potrebbe aggregare i dati e fornire una visione incompleta, tralasciando alcune informazioni che Google possiede effettivamente. Al contrario, effettuare chiamate giornaliere consente di segmentare le richieste e ricevere dati più granulari. Ogni chiamata per un singolo giorno assicura di raggiungere il massimo livello di dettaglio, riducendo il rischio che informazioni importanti vengano omesse.

Questo approccio è particolarmente utile per siti con un alto volume di traffico o numerose query uniche, dove i dati possono facilmente superare i limiti imposti dall’API. Utilizzando chiamate singole giornaliere, è possibile massimizzare l’output di dati ricevuti, garantendo un quadro completo delle performance del sito e migliorando la base informativa per le analisi SEO.

Vantaggi dello script

  • Automatizzazione: Automatizza l’estrazione dei dati senza dover accedere manualmente a Google Search Console.
  • Efficienza: Permette di analizzare grandi volumi di dati in modo rapido, migliorando il processo decisionale per strategie SEO.
  • Personalizzazione: Può essere facilmente modificato per includere ulteriori parametri o adattarsi a specifiche esigenze aziendali.
  • Compatibilità: Lo script è compatibile con librerie Python avanzate come pandas per facilitare analisi e visualizzazioni più dettagliate.

Limiti dello script

  • Configurazione iniziale: Richiede una configurazione iniziale, inclusa la creazione di un progetto Google Cloud e l’ottenimento delle credenziali API.
  • Limiti di utilizzo API: L’API di GSC ha limiti sulle richieste giornaliere. Superarli può bloccare temporaneamente l’accesso.
  • Conoscenze tecniche: È necessario avere familiarità con Python e i principi delle API REST per utilizzare e modificare lo script.

Casi di utilizzo

  1. Monitoraggio delle performance SEO: Ideale per agenzie e consulenti SEO che necessitano di analizzare regolarmente le prestazioni di siti web.
  2. Reportistica automatizzata: Può essere integrato in pipeline di reporting per generare report periodici senza intervento manuale.
  3. Analisi avanzata: I dati estratti possono essere utilizzati per analisi personalizzate, ad esempio, identificare le query con basso CTR o monitorare variazioni nella posizione media.
  4. Ottimizzazione di contenuti: Fornisce insight utili per migliorare le pagine del sito, come identificare keyword con alto volume di impressioni ma basso CTR.

Passaggi per l’utilizzo dello script

  1. Preparazione:
    • Creare un progetto Google Cloud e abilitare l’API di Google Search Console.
    • Generare e scaricare il file JSON delle credenziali di servizio.
    • Prepara il tuo ambiente virtuale python.
  2. Configurazione:
    • Lo script utilizza le seguenti librerie: os, argparse, sys, pandas, datetime, timedelta e googleapiclient (modulo sample_tools). Assicurati che queste librerie siano installate nell’ambiente Python in uso.
    • Modificare lo script per includere il percorso delle credenziali JSON e altri parametri di configurazione, come la property ed il periodo che si vuole analizzare.
  3. Esecuzione:
    • Eseguire lo script.
  4. Output:
    • Analizza l’Excel esportato, oppure modifica lo script per salvare i dati estratti in un formato preferito (CSV, JSON) per ulteriori analisi o integrazione con strumenti esterni.

Conclusione

Lo script gsc.py rappresenta uno strumento potente e versatile per chi lavora nel campo della SEO e desidera sfruttare al massimo i dati di Google Search Console. Sebbene richieda un minimo di configurazione iniziale e competenze tecniche, i vantaggi in termini di automazione e profondità di analisi sono significativi.

Per ulteriori dettagli sullo script e per il download, visita il repository ufficiale.

Articoli correlati

Autore

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *

Ultimi articoli aggiornati

Richiedi un preventivo SEO e Google Ads

Porta il tuo sito web al livello successivo con l’esperienza di EVE Milano. La nostra agenzia di Search Marketing ha ricevuto oltre 1196 richieste di preventivo, un segnale chiaro della fiducia che imprenditori e manager, come te, ripongono nella nostra specializzazione tecnica e verticale nella SEO e PPC. Se la tua organizzazione cerca competenze specifiche per emergere nei risultati di Google, noi siamo pronti a fornire quel valore aggiunto. Richiedi un preventivo ora e scopri la differenza tra noi e gli altri.
Richiedi un preventivo

Vuoi ricevere un avviso al mese con le nuove guide pubblicate?

Iscriviti alla newsletter!

Invia una richiesta a EVE Milano