Google Ad Library Company Ads
L’inventaire des publicités du Google Ads Transparency Center peut être énuméré à partir d’un ID d’annonceur ou d’un domaine d’entreprise choisis, puis affiné par des filtres de requête publics. Les identifiants de créations et les URL sources sont les valeurs les plus fiables au niveau de la liste, car l’enrichissement du détail de chaque publicité est désactivé pour cette opération.
Fonctionnalités de la Google Ad Library Company Ads API
- Point de départ : annonceur ou domaineIndiquez au moins un ID d’annonceur Google ou un domaine d’entreprise ; si les deux sont présents, c’est la source en amont qui définit leur intersection.
- Filtres d’inventaire validésAffinez l’index public des publicités par thème, région, période, surface Google ou format texte, image et vidéo.
- Collecte par curseurSuit les curseurs du fournisseur par pages de 40 enregistrements et s’arrête à la limite de 40–2 000 résultats demandée, à la dernière page, à une page vide ou à un curseur répété invalide.
- Enregistrements de publicités stablesRenvoie la forme de publicité normalisée commune, en conservant les champs de détail nuls ou vides au niveau de la liste au lieu d’inventer un enrichissement de la création.
Paramètres de la Google Ad Library Company Ads API
| Paramètres | Obligatoire | Description |
|---|---|---|
domain | Obligatoire (au moins un) | Domaine du site web de l’entreprise, par exemple lululemon.com. Au moins un des paramètres domain ou advertiser_id est obligatoire ; la correspondance par domaine peut couvrir plusieurs fiches d’annonceurs. |
advertiser_id | Obligatoire (au moins un) | Identifiant d’annonceur du Google Transparency Center, commençant généralement par AR. Au moins un des paramètres advertiser_id ou domain est obligatoire. |
topic | Facultatif | Filtre facultatif de thème de la source publique : all ou political. Le comportement du filtre et sa couverture restent définis par la source. |
region | Facultatif | Code de région facultatif, comme US, transmis en tant que contexte de requête public et non comme définition complète du ciblage. |
start_date | Facultatif | Filtre de date source facultatif, bornes incluses, au format YYYY-MM-DD. Il ne peut pas être postérieur à end_date lorsque les deux dates sont fournies. |
end_date | Facultatif | Filtre de date source facultatif au format YYYY-MM-DD. Il ne peut pas être antérieur à start_date lorsque les deux dates sont fournies. |
platform | Facultatif | Surface Google facultative : google_maps, google_play, google_search, google_shopping ou youtube. |
format | Facultatif | Format facultatif de la création : text, image ou video. Des variantes proches d’une même création peuvent tout de même apparaître comme enregistrements distincts. |
results_limit | Facultatif | Nombre maximal de publicités stockées. Vaut 40 par défaut et accepte les entiers de 40 à 2 000, par multiples de 40. |
Comment utiliser la Google Ad Library Company Ads API
Envoyez une requête structurée d’inventaire d’un annonceur, suivez sa tâche asynchrone, puis utilisez les URL de créations renvoyées pour récupérer le détail de manière ciblée.
- Choisissez un advertiser_id ou un domain ; n’ajoutez que les filtres utiles à votre question de comparaison ou de collecte.
- Fixez results_limit entre 40 et 2 000, par multiples de 40, puis envoyez la requête en POST à /v1/google-ad-library/company-ads.
- Interrogez /v1/tasks/{task_id} jusqu’à ce que la tâche réussisse ou échoue, puis parcourez si besoin les résultats stockés de la tâche.
- Considérez les ID et les URL de créations comme des enregistrements d’index ; envoyez les URL retenues à l’opération distincte de détail d’une publicité lorsque vous avez besoin de champs plus riches.
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 retrievalCas d’usage de la Google Ad Library Company Ads API
- Constituer une file de détails ciblée : Énumérez les ID de créations et les URL publiques d’un annonceur, puis ne retenez que les enregistrements pertinents pour des requêtes de détail plus riches.
- Comparer la répartition des formats observables : Dénombrez les enregistrements d’index de type texte, image et vidéo renvoyés, avec des identifiants, des filtres, des limites et des fenêtres de collecte constants.
- Examiner les fenêtres de diffusion divulguées : Repérez les créations renvoyées sous des filtres comparables de date, de région, de thème ou de surface Google, sans les prendre pour des données de ciblage privées.
Conseils d’expert pour la Google Ad Library Company Ads API
- Préférez un advertiser_id vérifié à un domaine trop large lorsque l’entité visée du Transparency Center est déjà connue.
- Gardez identifiants, filtres, results_limit et dates de collecte constants lorsque vous comparez des inventaires de publicités dans le temps.
- Attendez-vous à des valeurs nulles ou vides pour le texte, les dates, la destination, les impressions et les médias au niveau de la liste, car get_ad_details vaut toujours false.
- Voyez dans un résultat vide réussi l’absence de création exploitable pour les identifiants et filtres envoyés à ce moment-là, et non la preuve que l’entreprise n’a jamais fait de publicité.
API associées
En complément de la Google Ad Library Company Ads API, utilisez ces API lorsque vous avez besoin d’un autre type de données publiques Google Ad Library.
- Google Ad Library Ad API — Récupérez une création publique du Transparency Center à partir de son URL avec annonceur, texte, médias, diffusion, région, format, destination et impressions.
- Google Ad Library Advertiser Search API — Repérez des annonceurs publics du Transparency Center par requête et région facultative avec identité, site web, logo, région et nombre de publicités disponible.