Passer au contenu principal
Lisez le Google Ads Transparency Center en JSON via l’API asynchrone de tâches pour voir quelles publicités Google diffusent vos concurrents. ADS est un moteur à part entière : envoyez taskType ADS avec platform google_ads_transparency, et action choisit ce qu’il faut lire. La bibliothèque couvre les publicités sur Google Search, YouTube, Display, Google Play, Maps et Shopping dans tous les pays. Pour choisir entre les bibliothèques publicitaires, voir Bibliothèques publicitaires comparées.
  • search (par défaut) liste les publicités d’un annonceur avec advertiserId, de plusieurs concurrents à la fois avec advertiserIds, ou de tous les annonceurs dont les publicités renvoient vers un site web avec domain. Chaque publicité indique son format, son premier et son dernier jour de diffusion et le nombre de jours où elle a été diffusée, et la réponse se termine par un summary des publicités renvoyées.
  • advertisers trouve le advertiserId d’un annonceur à partir de son nom.
  • ad ouvre une publicité : son texte, sa vidéo et sa page de destination, et là où la bibliothèque les publie, les impressions par pays et par surface Google.
Une recherche coûte 0.5 crédit pour 30 publicités renvoyées. advertisers et ad coûtent 0.5 crédit chacun.

Requête

Soumettez la tâche, puis interrogez GET /v1/async/task/{id} ou recevez son webhook. Voir Tâches asynchrones.

Analyser les publicités d’un concurrent

Quatre requêtes couvrent une analyse de la concurrence :
  1. advertisers avec le nom du concurrent renvoie son advertiserId et les sites web que la bibliothèque suggère pour ce nom.
  2. search avec ce advertiserId, ou avec le domain du concurrent, liste ses publicités. activeDays montre quelles publicités sont diffusées depuis le plus longtemps, mediaType et publisherPlatforms répartissent les publicités par création et par surface, et summary compte les formats et les publicités lancées chaque semaine.
  3. ad avec le libraryId et le advertiserId d’une publicité renvoie son texte, sa vidéo, les pays qu’elle a touchés et, pour les publicités diffusées dans l’UE, ses impressions par pays et par surface.
  4. search avec advertiserIds compare jusqu’à 10 concurrents en une seule requête.

Paramètres

  • action : search (par défaut), advertisers ou ad.
  • query : le nom d’un annonceur, de 1 à 100 caractères. advertisers l’exige, et search et ad le rejettent.
  • advertiserId : l’ID d’un annonceur, comme AR16396071307843731457. search exige advertiserId, advertiserIds ou domain, et ad exige advertiserId.
  • advertiserIds : de 1 à 10 IDs d’annonceur, sous forme de tableau ou de texte séparé par des virgules. Envoyez advertiserIds ou advertiserId dans une même requête.
  • domain : un domaine simple comme nike.com. search liste les publicités qui renvoient vers lui, quel que soit l’annonceur qui les diffuse. domain et les IDs d’annonceur s’excluent mutuellement.
  • libraryId : l’ID de création d’une publicité, comme CR07264436911983296513. ad l’exige.
  • country : où les publicités ont été diffusées, sous forme de code pays à deux lettres, ou ALL pour tous les pays (par défaut). Un seul pays à la fois. search le lit.
  • publisherPlatforms : où les publicités ont été diffusées : search, youtube, maps, shopping ou play. Une seule valeur à la fois.
  • mediaType : all (par défaut), text, image ou video.
  • startDate, endDate : YYYY-MM-DD, envoyés ensemble. Conserve les publicités diffusées au moins une fois entre les deux jours.
  • limit : de 1 à 500 publicités sur search (par défaut 30), de 1 à 50 annonceurs sur advertisers (par défaut 30).
  • cursor : le nextCursor d’une réponse précédente, pour lire les publicités suivantes.
search lit advertiserId, advertiserIds, domain, country, publisherPlatforms, mediaType, startDate, endDate, limit et cursor. advertisers lit query et limit, et ad lit advertiserId et libraryId. Un champ que la bibliothèque ne peut pas rechercher, comme pageId, activeStatus ou sortBy, ou un champ que l’action ne lit pas, est rejeté avec 400 VALIDATION_ERROR, et details nomme le champ.

Comparer des concurrents

advertiserIds liste les publicités de jusqu’à 10 annonceurs en une seule requête. Le summary de la réponse compte les publicités de chaque annonceur, si bien qu’une requête montre qui diffuse le plus de publicités.

Lire plus de publicités

Une page de la bibliothèque contient jusqu’à 100 publicités, donc un limit supérieur à 100 lit plusieurs pages en une seule requête. Une réponse qui a encore des publicités à lire contient nextCursor. Envoyez-le comme cursor avec la même recherche pour recevoir les publicités suivantes, là encore jusqu’à limit. nextCursor vaut null lorsque la bibliothèque n’en a plus. Un curseur ne fonctionne qu’avec la recherche qui l’a renvoyé : un advertiserId, advertiserIds, domain, country, publisherPlatforms, mediaType ou une plage de dates différents est rejeté avec 400 VALIDATION_ERROR, tandis que limit peut changer.

Trouver un annonceur

action advertisers renvoie les annonceurs dont le nom correspond à query, tels que les suggère la zone de recherche de la bibliothèque. Envoyez le advertiserId que vous choisissez pour rechercher les publicités de cet annonceur.
Chaque annonceur a advertiserId, advertiserName, country (où l’annonceur est enregistré), verified, adCountRange (la fourchette de publicités de l’annonceur donnée par la bibliothèque, min et max) et libraryUrl, qui ouvre l’annonceur dans le Transparency Center. adCount vaut null parce que la bibliothèque donne une fourchette. domains liste les sites web que la bibliothèque suggère pour le nom, que search accepte comme domain. Un nom qu’aucun annonceur ne porte se termine avec advertisers vide. Une recherche d’annonceur n’accepte que query et limit, et coûte 0.5 crédit.

Réponse de recherche

  • La réponse reprend platform, action, country, advertiserId, advertiserIds ou domain, et les filtres reçus.
  • totalCountRange est l’estimation de la bibliothèque pour les publicités correspondantes, sous forme de min et max. totalCount vaut null. returnedCount compte les publicités dans ads, hasMore vaut true lorsque la bibliothèque en a davantage, ce que nextCursor lit, et libraryUrl ouvre la même recherche dans le Transparency Center.
  • Chaque publicité a position, libraryId, libraryUrl, advertiserId, advertiserName, format (TEXT, IMAGE ou VIDEO), width, height, images, videos, startDate, endDate, activeDays, isActive et landingDomain.
  • startDate et endDate sont le premier et le dernier jour où la bibliothèque montre la publicité (jours en UTC). activeDays compte les jours de startDate à endDate, les deux inclus, et vaut null lorsque la bibliothèque ne donne pas startDate. isActive vaut true pour une publicité diffusée pour la dernière fois aujourd’hui ou hier, car la bibliothèque publie la dernière fois qu’une publicité a été diffusée et non si elle est en cours.
  • landingDomain est l’hôte de la page de destination de la publicité, en minuscules et sans www., et vaut null lorsque la bibliothèque n’en donne pas.
  • Beaucoup de publicités textuelles arrivent sous forme d’image : images contient un lien vers la publicité telle que la bibliothèque la dessine, et le texte se trouve dans ad. title, body, ctaText et linkUrl valent null dans une recherche et sont remplis par ad lorsque l’aperçu de la publicité les contient. impressions est rempli par ad pour les publicités diffusées dans l’UE. platforms, targeting, payer et utm valent null.
  • summary compte les publicités de cette réponse : ads, activeAds, advertisers (les 10 qui ont le plus de publicités : advertiserId, advertiserName, ads), formats, landingDomains (les 10 qui ont le plus de publicités), oldestStartDate, newestStartDate et medianActiveDays. Il contient aussi launchesByWeek (les publicités lancées chaque semaine ISO, de la semaine la plus ancienne à la plus récente) et longestRunning (les 5 publicités avec le plus de activeDays). Une recherche avec limit 500 résume 500 publicités, et chaque page lue avec cursor porte le résumé de ses propres publicités.
  • Les liens d’image des publicités (tpc.googlesyndication.com) ne sont pas signés et restent ouverts. Les liens d’aperçu de ad sont signés et peuvent expirer.
  • Une recherche sans publicité correspondante se termine avec ads vide et un summary de 0 publicité.

Ce que la bibliothèque conserve

  • La bibliothèque montre les publicités de tous les pays. Une publicité reste environ 12 mois après le dernier jour où elle a été diffusée.
  • Les publicités diffusées dans l’UE comportent des impressions : une fourchette pour la publicité, pour chaque pays avec son premier et son dernier jour de diffusion, et pour chaque surface Google. Les publicités diffusées ailleurs comportent les pays que la publicité a touchés et le dernier jour de diffusion. Pour elles, ad lit le premier jour de diffusion (et activeDays) dans la liste de publicités de l’annonceur, la même valeur que renvoie search, et ne laisse startDate et activeDays à null que si la publicité ne figure pas parmi les 800 premières de la liste pour le pays touché ; debug.dates vaut detail, search ou not-found.
Pour conserver l’historique des publicités d’un concurrent, recherchez ses publicités à intervalles réguliers, par exemple chaque jour, et enregistrez-les.

Ouvrir une publicité

action ad ouvre la publicité avec le libraryId et le advertiserId que vous envoyez, tous deux issus d’une recherche. Elle renvoie la publicité, son annonceur et la transparence que la bibliothèque publie pour elle.
  • ad contient les champs d’une publicité de recherche, plus le texte de l’aperçu de la publicité : title, body, ctaText, displayUrl, linkUrl, longTitle, channelName, address et merchant, chacun lorsque la publicité le possède, et videos (url, previewUrl). previewKind nomme le type de publicité : text (Search), local (Maps, avec address), display (Display et YouTube) ou shopping (avec merchant). previewText liste les textes de l’aperçu, et previewUrl l’ouvre.
  • reachedCountries liste les pays où la publicité a été diffusée, sous forme de codes ISO.
  • impressions (min, max) est la fourchette d’impressions que la bibliothèque publie pour les publicités diffusées dans l’UE. Hors de l’UE, elle vaut null.
  • advertiser contient advertiserId, advertiserName et libraryUrl.
  • transparency contient startDate, endDate et impressions de la publicité, ses surfaces (surfaceId et la fourchette d’impressions de chaque surface Google ; platform nomme une surface uniquement lorsqu’elle est connue : SEARCH et MAPS) et ses countries, chacun avec ses propres startDate, endDate, impressions et surfaces. Pour une publicité diffusée hors de l’UE, transparency liste les pays avec leur dernier jour de diffusion, et les dates et impressions que la bibliothèque ne donne que pour l’UE valent null à cet endroit (le startDate propre à la publicité est lu dans la liste de publicités).
  • variants liste les rendus de la publicité que la bibliothèque conserve : width, height, imageUrl et previewUrl.
  • platforms et targeting valent null, car la bibliothèque ne publie aucun ciblage.
  • Un libraryId pour lequel la bibliothèque n’a aucune publicité échoue avec PAGE_UNAVAILABLE.

Tarif

Une recherche réserve 0.5 crédit pour 30 publicités que demande son limit, et facture 0.5 crédit pour 30 publicités renvoyées, avec un minimum de 0.5 crédit. La recherche par défaut de 30 publicités coûte 0.5 crédit, et une recherche avec limit 500 réserve 8.5 crédits. advertisers et ad coûtent 0.5 crédit chacun. Seules les requêtes terminées sont facturées.

Voir aussi