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
| Parametri | Obbligatorio | Descrizione |
|---|---|---|
domain | Obbligatorio (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_id | Obbligatorio (almeno uno) | Identificatore dell’inserzionista nel Google Transparency Center, che di norma inizia con AR. È richiesto almeno uno tra advertiser_id e domain. |
topic | Facoltativo | Filtro facoltativo per argomento della fonte pubblica: all o political. Il comportamento e la copertura del filtro restano definiti dalla fonte. |
region | Facoltativo | Codice regione facoltativo, come US, inoltrato come contesto di ricerca pubblico e non come definizione completa del targeting. |
start_date | Facoltativo | Filtro 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_date | Facoltativo | Filtro facoltativo di data della fonte in formato YYYY-MM-DD. Non può essere precedente a start_date quando vengono indicate entrambe le date. |
platform | Facoltativo | Superficie Google facoltativa: google_maps, google_play, google_search, google_shopping o youtube. |
format | Facoltativo | Formato del creativo facoltativo: text, image o video. Variazioni simili di un creativo possono comunque comparire come record separati. |
results_limit | Facoltativo | Numero 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.
- Scegli un advertiser_id o un domain; aggiungi solo i filtri pertinenti alla domanda di confronto o di raccolta.
- 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.
- Interroga /v1/tasks/{task_id} finché l’attività ha successo o fallisce, poi scorri i risultati salvati dell’attività, se serve.
- 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 retrievalCasi 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à.
API correlate
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.