AdSense Plumbing API: monitorare le entrate via script
L'AdSense Management API permette di scaricare in automatico report di entrate, performance e click direttamente da Google. E lo strumento ideale per editori che gestiscono più siti, agenzie e chi vuole costruire dashboard custom integrate con il proprio CRM o BI.
Cosa permette di fare l'API
L'AdSense API offre accesso programmatico a tutti i report disponibili nella dashboard: entrate per data, ad unit, paese, formato, dispositivo. Permette esportazione in JSON o CSV, query con filtri custom, intervalli temporali flessibili, accesso a più account AdSense con OAuth delegato. Utile per consolidare dati di clienti diversi in un'unica vista.
Setup iniziale
- Crea progetto Google Cloud: console.cloud.google.com, nuovo progetto.
- Abilita AdSense Management API: dalla libreria API.
- Crea credenziali OAuth 2.0: tipo "Applicazione Web" con redirect URI.
- Configura schermata consenso: nome app, dominio, scopes adsense.readonly.
- Scarica le credenziali: file JSON con client_id e client_secret.
Esempio in Python
Con la libreria google-api-python-client e google-auth, lo script tipico autentica via OAuth, ottiene refresh token, costruisce il client AdSense, chiama il metodo accounts.reports.generate con parametri startDate, endDate, metrics e dimensions. Risultato in JSON che puoi parsare con pandas per analisi successive o inviare a database.
Esempio in PHP
Con la libreria google/apiclient via Composer, simile struttura: client OAuth, classe Google_Service_Adsense, metodo accounts_reports->generate con array di parametri. Risultato accessibile come array PHP, perfetto per integrare in dashboard WordPress o CMS custom. Cura il caching dei token per non chiamare ogni volta Google.
Casi d'uso pratici
Tra i casi più utili: dashboard giornaliera entrate aggregate di più siti, alert via email/Slack quando le entrate calano oltre soglia, integrazione con sistema fatturazione per emettere fattura automatica a Google, report mensile clienti dell'agenzia, confronto YoY automatizzato con grafici, esportazione in BigQuery per analisi avanzata.
Errori comuni e come risolverli
- Quota API esaurita: 10.000 richieste/giorno per progetto. Implementa caching e batch query.
- Token scaduto: l'access token dura 1 ora. Usa sempre refresh token per riautenticare automaticamente.
- Date in formato sbagliato: AdSense API vuole YYYY-MM-DD. Errore frequente con localizzazione italiana.
- Filtri sintassi: usa la documentazione ufficiale dimensions/metrics, non improvvisare.
Domande frequenti
D: L'API e gratuita?
R: Si, completamente gratuita entro le quote standard Google Cloud.
D: Posso accedere ai dati in real-time?
R: I dati AdSense hanno ritardo di 1-2 ore. Per real-time servono partner integrations enterprise.
D: L'API supporta scrittura (es. modificare ad unit)?
R: No, l'AdSense Management API e solo lettura. La gestione si fa via dashboard.
Approfondimento: visione strategica
Lavorare con AdSense richiede una visione strategica che vada oltre il dato di oggi. Editori di successo pensano per cicli annuali, considerando stagionalita Q4 (boost natalizio +40-60%), Q1 (calo post-natalizio), Q2-Q3 (assestamento). Pianificare il calendario editoriale in coerenza con questi cicli (es. articoli evergreen "Best of" da agosto per indicizzazione in tempo per acquisti natalizi) e una pratica vincente.
Anche la diversificazione delle fonti di traffico e fondamentale: dipendere al 90% da Google organico rende vulnerabili a core update. Mix sano: 50-60% organico, 15-25% direct/return visitors, 10-15% email/newsletter, 5-10% social/referral. Editori con questo mix subiscono meno gli scossoni algoritmici.
Caso pratico
Un blog verticale di dieta e nutrizione era arrivato a 8.000 euro/mese AdSense. Un core update Google nel 2025 ha ridimensionato il traffico del 35% in due settimane (problema EEAT con autori non riconoscibili). Ricavi crollati a 5.000 euro/mese. Risposta: assunzione di nutrizionisti come ghost author con bio dettagliata e foto, ristrutturazione contenuti con citazioni scientifiche, accreditamento medico verificabile. Dopo 4 mesi traffico recuperato e ricavi a 9.500 euro/mese, oltre il precedente.
Glossario
- Ad unit: singola unita pubblicitaria configurata in AdSense.
- Publisher ID: identificativo unico dell'editore (formato pub-XXXXXXXXX).
- Asta open: meccanismo Google di asta aperta su impressioni in tempo reale.
- Header bidding: tecnica di asta lato client per massimizzare bid.
- Dwell time: tempo di permanenza dell'utente sul sito dopo click in SERP.
Risorse utili
Per restare aggiornati sulle evoluzioni segnaliamo: il centro assistenza ufficiale di Google AdSense (support.google.com/adsense), il blog Inside AdSense per news e best practice ufficiali, la community Reddit r/Adsense per confronto fra editori, i forum italiani come AdSenseItalia per casi locali. Anche YouTube ha canali dedicati come "AdSense in Italiano" e canali ufficiali Google.
Per analisi tecniche più approfondite sono fondamentali strumenti come PageSpeed Insights, Search Console, Google Analytics 4, Lighthouse e WebPageTest. Per chi gestisce più siti o agenzie, software come Ezoic, Snigel o Mediavine offrono dashboard avanzate e ottimizzazione automatica. Una buona pratica e dedicare 30 minuti a settimana a leggere aggiornamenti di settore per anticipare cambiamenti.
La community italiana di editori AdSense e attiva su gruppi Facebook e Telegram dedicati. Partecipare permette di scambiare esperienze concrete, anticipare problemi e trovare partner per progetti collaborativi. Tieni sempre presente che ogni sito ha caratteristiche uniche: le best practice sono punti di partenza, non regole assolute.
Hai bisogno di aiuto?
Se vuoi integrare l'AdSense API nel tuo sistema gestionale o creare una dashboard custom, il team di G Tech Group puo sviluppare la soluzione. Contattaci tramite il modulo di contatto.