google-ad-library/
company-ads

Elenca i record pubblici filtrati dei creativi del Google Ads Transparency Center per ID dell’inserzionista o dominio, con identità normalizzata del creativo, URL di origine, pubblicazione, formato e campi di dettaglio disponibili.

Google Ad Library Company Ads API

Inventario dell’inserzionista
Paginazione da 40 record
Indice dei creativi filtrabile
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 Company Ads

L’inventario dei creativi del Google Ads Transparency Center può essere elencato a partire dall’ID di un inserzionista selezionato o dal dominio di un’azienda e ristretto con filtri di ricerca pubblici. Gli identificatori dei creativi e gli URL di origine sono i valori più affidabili a livello di elenco, perché l’arricchimento dei dettagli per singolo annuncio è disattivato per questa operazione.

Funzionalità della Google Ad Library Company Ads API

  • Punto di partenza: inserzionista o dominioFornisci almeno un ID di inserzionista Google o un dominio aziendale; quando sono presenti entrambi, la fonte a monte definisce come si intersecano.
  • Filtri di inventario convalidatiRestringi l’indice pubblico dei creativi per argomento, regione, intervallo di date, superficie Google o valori di formato testo, immagine e video.
  • Raccolta a cursoreSegue i cursori del provider in pagine da 40 record e si ferma al limite di risultati richiesto, da 40 a 2.000, all’ultima pagina, a una pagina vuota o a un cursore ripetuto non valido.
  • Record di annunci stabiliRestituisce la forma condivisa e normalizzata dell’annuncio, mantenendo i campi di dettaglio a livello di elenco nulli o vuoti invece di inventare un arricchimento dei creativi.

Parametri della Google Ad Library Company Ads API

ParametriObbligatorioDescrizione
domainObbligatorio (almeno uno)Dominio del sito web di un’azienda, come lululemon.com. È richiesto almeno uno tra domain e advertiser_id; la corrispondenza del dominio può estendersi a più di un record di inserzionista.
advertiser_idObbligatorio (almeno uno)Identificatore dell’inserzionista nel Google Transparency Center, che di norma inizia con AR. È richiesto almeno uno tra advertiser_id e domain.
topicFacoltativoFiltro facoltativo per argomento della fonte pubblica: all o political. Il comportamento e la copertura del filtro restano definiti dalla fonte.
regionFacoltativoCodice regione facoltativo, come US, inoltrato come contesto di ricerca pubblico e non come definizione completa del targeting.
start_dateFacoltativoFiltro facoltativo di data della fonte, estremo incluso, in formato YYYY-MM-DD. Non può essere successivo a end_date quando vengono indicate entrambe le date.
end_dateFacoltativoFiltro facoltativo di data della fonte in formato YYYY-MM-DD. Non può essere precedente a start_date quando vengono indicate entrambe le date.
platformFacoltativoSuperficie Google facoltativa: google_maps, google_play, google_search, google_shopping o youtube.
formatFacoltativoFormato del creativo facoltativo: text, image o video. Variazioni simili di un creativo possono comunque comparire come record separati.
results_limitFacoltativoNumero massimo di record di creativi salvati. Il valore predefinito è 40 e accetta numeri interi da 40 a 2.000 in multipli di 40.

Come usare la Google Ad Library Company Ads API

Invia una richiesta strutturata di inventario di un inserzionista, segui la relativa attività asincrona e usa gli URL dei creativi restituiti per recuperare i dettagli in modo selettivo.

  1. Scegli un advertiser_id o un domain; aggiungi solo i filtri pertinenti alla domanda di confronto o di raccolta.
  2. Imposta results_limit tra 40 e 2.000 in multipli di 40, poi invia con POST la richiesta a /v1/google-ad-library/company-ads.
  3. Interroga /v1/tasks/{task_id} finché l’attività ha successo o fallisce, poi scorri i risultati salvati dell’attività, se serve.
  4. Tratta gli ID e gli URL dei creativi come record di indice; invia gli URL selezionati alla separata operazione di dettaglio dell’annuncio quando servono campi più ricchi.
curl -X POST "https://api.socq.ai/v1/google-ad-library/company-ads" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id":"AR01614014350098432001","region":"US","format":"video","results_limit":80}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and select creative URLs for detail retrieval

Casi d’uso della Google Ad Library Company Ads API

  • Creare una coda di dettaglio selettiva: Elenca ID dei creativi e URL pubblici di un inserzionista, poi scegli solo i record pertinenti per richieste di dettaglio più ricche.
  • Confrontare le combinazioni di formati osservabili: Conta i record di indice di testo, immagine e video restituiti, con identificatori, filtri, limiti e finestre di raccolta coerenti.
  • Rivedere le finestre di pubblicazione dichiarate: Individua i record di creativi restituiti con filtri comparabili di data, regione, argomento o superficie Google, senza considerarli dati di targeting privati.

Consigli degli esperti per la Google Ad Library Company Ads API

  • Preferisci un advertiser_id verificato a un dominio generico quando l’entità del Transparency Center è già nota.
  • Mantieni coerenti identificatori, filtri, results_limit e date di raccolta quando confronti nel tempo gli inventari dei creativi.
  • Aspettati che testo, date, destinazione, impression e media siano nulli o vuoti a livello di elenco, perché get_ad_details è sempre false.
  • Considera un risultato vuoto riuscito come assenza di creativi utilizzabili con gli identificatori e i filtri inviati in quel momento, non come prova che l’azienda non abbia mai fatto pubblicità.

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

  • Google Ad Library Ad API — Recupera una creatività pubblica nota del Transparency Center tramite URL, con inserzionista, testo, media, diffusione, regione, formato, destinazione e impression.
  • 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.

Esplora altre piattaforme

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

Google Ad Library Company Ads API — FAQ

Google Ad Library Company Ads API è un’interfaccia programmatica per elencare i record dell’indice pubblico dei creativi del Google Ads Transparency Center per ID dell’inserzionista o dominio e filtri facoltativi. Restituisce record di annunci normalizzati, con ID dei creativi e URL pubblici in genere più affidabili dei campi di dettaglio.

È richiesto almeno uno dei due. Un ID di inserzionista è normalmente più preciso, mentre un dominio può corrispondere a record di più entità pubbliche di inserzionisti; se fornisci entrambi, vengono inoltrati insieme.

Il valore predefinito è 40 e deve essere un numero intero da 40 a 2.000 in multipli di 40. SocQ segue i cursori del provider e tronca le righe salvate a quel limite.

La richiesta di elenco invia sempre get_ad_details=false. I campi dello schema stabile restano dichiarati, ma i valori assenti di testo, media, destinazione, pubblicazione o impression non vengono dedotti.

Ogni record di creativo salvato costa 0,5 crediti SocQ. La stima presuppone 40 risultati e ammette uno scostamento in eccesso; un risultato vuoto riuscito comporta solo la quota base configurata a zero crediti.