google-ad-library/
ad

Recupera un creativo pubblico del Google Ads Transparency Center dal suo URL esatto, con identità dell’inserzionista, testo, media, date di pubblicazione, regioni, formato, destinazione e impression disponibili in un record normalizzato.

Google Ad Library Ad API

URL esatto del creativo
Inserzionista e media
Contesto pubblico di pubblicazione
0,5 crediti per risultato
Pronto
Pronto

Inserisci i parametri e invia una richiesta. Qui compariranno lo stato dell’attività e i risultati normalizzati.

README

A cura di SocQ · Aggiornato il

Google Ad Library Ad

I creativi del Google Ads Transparency Center sono record pubblicitari pubblici con identità dell’inserzionista, testo e media visibili, link di destinazione, formati, date di pubblicazione, regioni e dati sulle impression disponibili. Questi dettagli supportano la verifica dei creativi, l’arricchimento di annunci selezionati, la ricerca sul contesto di pubblicazione e i confronti tra archivi puntuali nel tempo.

Funzionalità della Google Ad Library Ad API

  • Risoluzione esatta del creativoRisolve un URL adstransparency.google.com che contiene /creative/ in al massimo un record pubblicitario pubblico normalizzato, senza estendere la richiesta a una ricerca.
  • Campi di inserzionista e creativoRestituisce l’identificatore del creativo, l’URL di origine pubblico, il testo disponibile, il riferimento all’inserzionista, la destinazione e il formato in uno schema stabile dell’annuncio.
  • Contesto di pubblicazioneConserva le date di inizio e fine disponibili, i paesi, i posizionamenti e un valore scalare delle impression solo quando i dati della fonte possono essere normalizzati in modo sicuro.
  • Asset media normalizzatiEspone i riferimenti disponibili a immagini o video con miniature, dimensioni e durata, omettendo i valori facoltativi assenti.

Parametri della Google Ad Library Ad API

ParametriObbligatorioDescrizione
urlObbligatorioURL pubblico obbligatorio di un creativo del Google Ads Transparency Center. Lo schema deve essere http o https, l’host deve terminare con adstransparency.google.com e il percorso deve contenere /creative/.

Come usare la Google Ad Library Ad API

Invia l’URL pubblico esatto di un creativo, segui l’attività asincrona e leggi il record normalizzato dell’annuncio dalla struttura standard dei risultati.

  1. Prepara un URL http o https su adstransparency.google.com il cui percorso contiene /creative/.
  2. Invia url con POST a /v1/google-ad-library/ad e salva il task_id restituito.
  3. Interroga /v1/tasks/{task_id} finché l’attività ha successo o fallisce.
  4. Leggi data.results.items; l’operazione di dettaglio restituisce al massimo un elemento, quindi has_more è normalmente false e next_cursor è normalmente null.
curl -X POST "https://api.socq.ai/v1/google-ad-library/ad" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR10449491775734153217"}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items; this detail operation returns at most one item

Casi d’uso della Google Ad Library Ad API

  • Arricchire un creativo selezionato: Usa ID del creativo, riferimento all’inserzionista, testo, destinazione, formato, media e URL di origine per completare un record pubblicitario individuato in precedenza.
  • Verificare le prove pubbliche di pubblicazione: Confronta date, paesi, posizionamenti e impression disponibili per documentare dove e quando un creativo noto è stato osservato pubblicamente.
  • Archiviare istantanee dei creativi: Salva testo, media, inserzionista, pubblicazione, destinazione e i campi collected_at normalizzati per un successivo confronto puntuale nel tempo.

Consigli degli esperti per la Google Ad Library Ad API

  • Invia l’URL completo del creativo e non un semplice identificatore CR o l’URL di un inserzionista, così l’host e il percorso /creative/ superano la validazione.
  • Tratta separatamente un’attività riuscita senza alcun elemento da un errore del provider; un creativo rimosso, con restrizioni o non disponibile può non produrre alcun record utilizzabile.
  • Conserva come nullable i campi di pubblicazione, testo, destinazione, inserzionista, impression e media, invece di convertire i valori pubblici mancanti in zero o in affermazioni vuote.
  • Usa la ricerca degli inserzionisti e gli annunci dell’azienda per le attività di scoperta o di inventario; questa operazione di dettaglio risolve deliberatamente solo il creativo inviato.

Oltre alla Google Ad Library Ad API, usa queste API quando ti serve un altro tipo di dati pubblici di Google Ad Library.

  • Google Ad Library Advertiser Search API — Individua gli inserzionisti pubblici candidati del Transparency Center per query e regione facoltativa, con identità, sito web, logo, regione e numero di annunci disponibile.
  • Google Ad Library Company Ads API — Raccoglie le creatività pubbliche del Transparency Center per dominio dell’azienda o ID dell’inserzionista con controlli su argomento, regione, data, superficie, formato e numero massimo di risultati.

Esplora altre piattaforme

Combina i dati di Google Ad Library con i dati pubblici delle altre piattaforme social supportate.

Google Ad Library Ad API — FAQ

Google Ad Library Ad API è un’interfaccia programmatica per recuperare un creativo pubblico del Google Ads Transparency Center dal suo URL esatto. Restituisce campi normalizzati di inserzionista, testo, media, pubblicazione, regione, formato, destinazione e impression disponibili.

Invia un URL http o https il cui host termina con adstransparency.google.com e il cui percorso contiene /creative/. Non sono accettati ID di creativi isolati, URL di inserzionisti, domini, query ed elenchi di URL.

Il record normalizzato dichiara identità, URL di origine, testo, inserzionista, date di pubblicazione, paesi, piattaforme, formato, destinazione, impression, media, orario di pubblicazione e orario di raccolta. I campi che dipendono dalla fonte restano nullable e i media possono essere vuoti.

Un URL di creativo valido può riferirsi a un record pubblico rimosso, con restrizioni, malformato o al momento non disponibile. L’endpoint non sostituisce un altro creativo né trasforma la richiesta in una ricerca.

Ogni record restituito costa 0,5 crediti SocQ. La policy configurata per i risultati vuoti addebita solo la quota base a zero crediti quando non viene restituito alcun record.