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 avecadvertiserId, de plusieurs concurrents à la fois avecadvertiserIds, ou de tous les annonceurs dont les publicités renvoient vers un site web avecdomain. 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 unsummarydes publicités renvoyées.advertiserstrouve leadvertiserIdd’un annonceur à partir de son nom.adouvre 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.
advertisers et ad coûtent 0.5 crédit chacun.
Requête
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 :advertisersavec le nom du concurrent renvoie sonadvertiserIdet les sites web que la bibliothèque suggère pour ce nom.searchavec ceadvertiserId, ou avec ledomaindu concurrent, liste ses publicités.activeDaysmontre quelles publicités sont diffusées depuis le plus longtemps,mediaTypeetpublisherPlatformsrépartissent les publicités par création et par surface, etsummarycompte les formats et les publicités lancées chaque semaine.adavec lelibraryIdet leadvertiserIdd’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.searchavecadvertiserIdscompare jusqu’à 10 concurrents en une seule requête.
Paramètres
action:search(par défaut),advertisersouad.query: le nom d’un annonceur, de 1 à 100 caractères.advertisersl’exige, etsearchetadle rejettent.advertiserId: l’ID d’un annonceur, commeAR16396071307843731457.searchexigeadvertiserId,advertiserIdsoudomain, etadexigeadvertiserId.advertiserIds: de 1 à 10 IDs d’annonceur, sous forme de tableau ou de texte séparé par des virgules. EnvoyezadvertiserIdsouadvertiserIddans une même requête.domain: un domaine simple commenike.com.searchliste les publicités qui renvoient vers lui, quel que soit l’annonceur qui les diffuse.domainet les IDs d’annonceur s’excluent mutuellement.libraryId: l’ID de création d’une publicité, commeCR07264436911983296513.adl’exige.country: où les publicités ont été diffusées, sous forme de code pays à deux lettres, ouALLpour tous les pays (par défaut). Un seul pays à la fois.searchle lit.publisherPlatforms: où les publicités ont été diffusées :search,youtube,maps,shoppingouplay. Une seule valeur à la fois.mediaType:all(par défaut),text,imageouvideo.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 sursearch(par défaut 30), de 1 à 50 annonceurs suradvertisers(par défaut 30).cursor: lenextCursord’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 unlimit 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.
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,advertiserIdsoudomain, et les filtres reçus. totalCountRangeest l’estimation de la bibliothèque pour les publicités correspondantes, sous forme deminetmax.totalCountvautnull.returnedCountcompte les publicités dansads,hasMorevauttruelorsque la bibliothèque en a davantage, ce quenextCursorlit, etlibraryUrlouvre la même recherche dans le Transparency Center.- Chaque publicité a
position,libraryId,libraryUrl,advertiserId,advertiserName,format(TEXT,IMAGEouVIDEO),width,height,images,videos,startDate,endDate,activeDays,isActiveetlandingDomain. startDateetendDatesont le premier et le dernier jour où la bibliothèque montre la publicité (jours en UTC).activeDayscompte les jours destartDateàendDate, les deux inclus, et vautnulllorsque la bibliothèque ne donne passtartDate.isActivevauttruepour 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.landingDomainest l’hôte de la page de destination de la publicité, en minuscules et sanswww., et vautnulllorsque la bibliothèque n’en donne pas.- Beaucoup de publicités textuelles arrivent sous forme d’image :
imagescontient un lien vers la publicité telle que la bibliothèque la dessine, et le texte se trouve dansad.title,body,ctaTextetlinkUrlvalentnulldans une recherche et sont remplis paradlorsque l’aperçu de la publicité les contient.impressionsest rempli paradpour les publicités diffusées dans l’UE.platforms,targeting,payeretutmvalentnull. summarycompte 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,newestStartDateetmedianActiveDays. Il contient aussilaunchesByWeek(les publicités lancées chaque semaine ISO, de la semaine la plus ancienne à la plus récente) etlongestRunning(les 5 publicités avec le plus deactiveDays). Une recherche aveclimit500 résume 500 publicités, et chaque page lue aveccursorporte 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 deadsont signés et peuvent expirer. - Une recherche sans publicité correspondante se termine avec
adsvide et unsummaryde0publicité.
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,
adlit le premier jour de diffusion (etactiveDays) dans la liste de publicités de l’annonceur, la même valeur que renvoiesearch, et ne laissestartDateetactiveDaysànullque si la publicité ne figure pas parmi les 800 premières de la liste pour le pays touché ;debug.datesvautdetail,searchounot-found.
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.
adcontient les champs d’une publicité de recherche, plus le texte de l’aperçu de la publicité :title,body,ctaText,displayUrl,linkUrl,longTitle,channelName,addressetmerchant, chacun lorsque la publicité le possède, etvideos(url,previewUrl).previewKindnomme le type de publicité :text(Search),local(Maps, avecaddress),display(Display et YouTube) oushopping(avecmerchant).previewTextliste les textes de l’aperçu, etpreviewUrll’ouvre.reachedCountriesliste 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 vautnull.advertisercontientadvertiserId,advertiserNameetlibraryUrl.transparencycontientstartDate,endDateetimpressionsde la publicité, sessurfaces(surfaceIdet la fourchette d’impressions de chaque surface Google ;platformnomme une surface uniquement lorsqu’elle est connue :SEARCHetMAPS) et sescountries, chacun avec ses propresstartDate,endDate,impressionsetsurfaces. Pour une publicité diffusée hors de l’UE,transparencyliste les pays avec leur dernier jour de diffusion, et les dates et impressions que la bibliothèque ne donne que pour l’UE valentnullà cet endroit (lestartDatepropre à la publicité est lu dans la liste de publicités).variantsliste les rendus de la publicité que la bibliothèque conserve :width,height,imageUrletpreviewUrl.platformsettargetingvalentnull, car la bibliothèque ne publie aucun ciblage.- Un
libraryIdpour lequel la bibliothèque n’a aucune publicité échoue avecPAGE_UNAVAILABLE.
Tarif
Une recherche réserve 0.5 crédit pour 30 publicités que demande sonlimit, 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.