taskType ADS mit platform google_ads_transparency, und action wählt, was gelesen wird. Die Bibliothek deckt Anzeigen auf Google Search, YouTube, Display, Google Play, Maps und Shopping in jedem Land ab. Zur Auswahl zwischen den Werbebibliotheken siehe Werbebibliotheken im Vergleich.
search(Standard) listet die Anzeigen eines Werbetreibenden mitadvertiserId, mehrerer Wettbewerber gleichzeitig mitadvertiserIdsoder aller Werbetreibenden, deren Anzeigen auf eine Website verlinken, mitdomainauf. Jede Anzeige enthält ihr Format, ihren ersten und letzten Ausspielungstag und wie viele Tage sie lief, und die Antwort endet mit einersummaryder gelieferten Anzeigen.advertisersfindet dieadvertiserIdeines Werbetreibenden anhand seines Namens.adöffnet eine Anzeige: ihren Text, ihr Video und ihre Zielseite und, soweit die Bibliothek sie veröffentlicht, die Impressionen nach Land und nach Google-Oberfläche.
advertisers und ad kosten je 0.5 Credits.
Anfrage
GET /v1/async/task/{id} ab oder empfangen Sie den Webhook. Siehe Asynchrone Tasks.
Anzeigen eines Wettbewerbers analysieren
Vier Anfragen decken eine Wettbewerbsanalyse ab:advertisersmit dem Namen des Wettbewerbers liefert dessenadvertiserIdund die Websites, die die Bibliothek für den Namen vorschlägt.searchmit dieseradvertiserIdoder mit derdomaindes Wettbewerbers listet seine Anzeigen auf.activeDayszeigt, welche Anzeigen am längsten laufen,mediaTypeundpublisherPlatformsgliedern die Anzeigen nach Creative und Oberfläche, undsummaryzählt die Formate und die Anzeigen, die in jeder Woche gestartet sind.admit derlibraryIdund deradvertiserIdeiner Anzeige liefert ihren Text, ihr Video, die erreichten Länder und, bei in der EU ausgespielten Anzeigen, ihre Impressionen nach Land und Oberfläche.searchmitadvertiserIdsvergleicht bis zu 10 Wettbewerber in einer Anfrage.
Parameter
action:search(Standard),advertisersoderad.query: Der Name eines Werbetreibenden, 1 bis 100 Zeichen.advertisersverlangt ihn, undsearchundadlehnen ihn ab.advertiserId: Die ID eines Werbetreibenden, etwaAR16396071307843731457.searchbrauchtadvertiserId,advertiserIdsoderdomain, undadverlangtadvertiserId.advertiserIds: 1 bis 10 Werbetreibenden-IDs als Array oder kommagetrennter Text. Senden Sie in einer AnfrageadvertiserIdsoderadvertiserId.domain: Eine reine Domain wienike.com.searchlistet die Anzeigen auf, die darauf verlinken, unabhängig davon, welcher Werbetreibende sie schaltet.domainund die Werbetreibenden-IDs schließen sich gegenseitig aus.libraryId: Die Creative-ID einer Anzeige, etwaCR07264436911983296513.adverlangt sie.country: Wo die Anzeigen ausgespielt wurden, als zweistelliger Ländercode, oderALLfür alle Länder (Standard). Jeweils ein Land.searchliest es.publisherPlatforms: Wo die Anzeigen liefen:search,youtube,maps,shoppingoderplay. Jeweils ein Wert.mediaType:all(Standard),text,imageodervideo.startDate,endDate:YYYY-MM-DD, gemeinsam zu senden. Behält die Anzeigen, die zwischen den beiden Tagen mindestens einmal ausgespielt wurden.limit: 1 bis 500 Anzeigen beisearch(Standard 30), 1 bis 50 Werbetreibende beiadvertisers(Standard 30).cursor: DernextCursoreiner früheren Antwort, um die darauffolgenden Anzeigen zu lesen.
search liest advertiserId, advertiserIds, domain, country, publisherPlatforms, mediaType, startDate, endDate, limit und cursor. advertisers liest query und limit, und ad liest advertiserId und libraryId. Ein Feld, das die Bibliothek nicht durchsuchen kann, etwa pageId, activeStatus oder sortBy, oder ein Feld, das die Aktion nicht liest, wird mit 400 VALIDATION_ERROR abgelehnt, und details nennt das Feld.
Wettbewerber vergleichen
advertiserIds listet die Anzeigen von bis zu 10 Werbetreibenden in einer Anfrage auf. Die summary der Antwort zählt die Anzeigen jedes Werbetreibenden, sodass eine Anfrage zeigt, wer die meisten Anzeigen schaltet.
Weitere Anzeigen lesen
Eine Seite der Bibliothek enthält bis zu 100 Anzeigen, daher liest einlimit über 100 mehrere Seiten in einer Anfrage. Eine Antwort mit weiteren zu lesenden Anzeigen enthält nextCursor. Senden Sie ihn mit derselben Suche als cursor, um die nächsten Anzeigen zu erhalten, wieder bis zu limit. nextCursor ist null, sobald die Bibliothek keine weiteren hat.
Ein Cursor funktioniert nur mit der Suche, die ihn geliefert hat: Eine andere advertiserId, advertiserIds, domain, country, publisherPlatforms, mediaType oder ein anderer Datumsbereich wird mit 400 VALIDATION_ERROR abgelehnt, während sich limit ändern darf.
Werbetreibenden finden
action advertisers liefert die Werbetreibenden, deren Namen auf query passen, so wie das Suchfeld der Bibliothek sie vorschlägt. Senden Sie die gewählte advertiserId, um die Anzeigen dieses Werbetreibenden zu suchen.
advertiserId, advertiserName, country (wo der Werbetreibende registriert ist), verified, adCountRange (die Spanne der Anzeigen des Werbetreibenden laut Bibliothek, min und max) und libraryUrl, die den Werbetreibenden im Transparency Center öffnet. adCount ist null, weil die Bibliothek eine Spanne liefert. domains listet die Websites, die die Bibliothek für den Namen vorschlägt und die search als domain annimmt. Ein Name, den kein Werbetreibender trägt, endet mit leerem advertisers. Eine Werbetreibenden-Suche nimmt nur query und limit an und kostet 0.5 Credits.
Such-Antwort
- Die Antwort gibt
platform,action,country,advertiserId,advertiserIdsoderdomainund die erhaltenen Filter zurück. totalCountRangeist die Schätzung der Bibliothek für die passenden Anzeigen, alsminundmax.totalCountistnull.returnedCountzählt die Anzeigen inads,hasMoreisttrue, wenn die Bibliothek mehr hat, dienextCursorliest, undlibraryUrlöffnet dieselbe Suche im Transparency Center.- Jede Anzeige hat
position,libraryId,libraryUrl,advertiserId,advertiserName,format(TEXT,IMAGEoderVIDEO),width,height,images,videos,startDate,endDate,activeDays,isActiveundlandingDomain. startDateundendDatesind der erste und der letzte Tag, an dem die Bibliothek die Anzeige zeigt (Tage in UTC).activeDayszählt die Tage vonstartDatebisendDate, beide mitgezählt, und istnull, wenn die Bibliothek keinstartDateliefert.isActiveisttruefür eine Anzeige, die zuletzt heute oder gestern ausgespielt wurde, weil die Bibliothek veröffentlicht, wann eine Anzeige zuletzt ausgespielt wurde, und nicht, ob sie läuft.landingDomainist der Host der Zielseite der Anzeige, in Kleinbuchstaben und ohnewww., undnull, wo die Bibliothek keinen liefert.- Viele Textanzeigen kommen als Bild:
imagesenthält einen Link zur Anzeige, wie die Bibliothek sie darstellt, und der Text steht inad.title,body,ctaTextundlinkUrlsind in einer Suchenullund werden vonadgefüllt, wenn die Vorschau der Anzeige sie enthält.impressionswird vonadfür in der EU ausgespielte Anzeigen gefüllt.platforms,targeting,payerundutmsindnull. summaryzählt die Anzeigen dieser Antwort:ads,activeAds,advertisers(die 10 mit den meisten Anzeigen:advertiserId,advertiserName,ads),formats,landingDomains(die 10 mit den meisten Anzeigen),oldestStartDate,newestStartDateundmedianActiveDays. Es enthält außerdemlaunchesByWeek(die Anzeigen, die in jeder ISO-Woche starteten, älteste Woche zuerst) undlongestRunning(die 5 Anzeigen mit den meistenactiveDays). Eine Suche mitlimit500 fasst 500 Anzeigen zusammen, und jede mitcursorgelesene Seite enthält die Zusammenfassung ihrer eigenen Anzeigen.- Bild-Links von Anzeigen (
tpc.googlesyndication.com) sind nicht signiert und bleiben offen. Die Vorschau-Links vonadsind signiert und können ablaufen. - Eine Suche ohne passende Anzeigen endet mit leerem
adsund einersummarymit0Anzeigen.
Was die Bibliothek aufbewahrt
- Die Bibliothek zeigt Anzeigen aus jedem Land. Eine Anzeige bleibt etwa 12 Monate nach dem letzten Tag, an dem sie ausgespielt wurde, erhalten.
- In der EU ausgespielte Anzeigen enthalten Impressionen: eine Spanne für die Anzeige, für jedes Land mit seinem ersten und letzten Ausspielungstag und für jede Google-Oberfläche. Anderswo ausgespielte Anzeigen enthalten die Länder, die die Anzeige erreichte, und den letzten Ausspielungstag. Bei ihnen liest
adden ersten Ausspielungstag (undactiveDays) aus der Anzeigenliste des Werbetreibenden, denselben Wert, densearchliefert, und läsststartDateundactiveDaysnur dannnull, wenn die Anzeige nicht unter den ersten 800 Anzeigen der Liste für das erreichte Land steht;debug.datesistdetail,searchodernot-found.
Eine Anzeige öffnen
action ad öffnet die Anzeige mit der libraryId und der advertiserId, die Sie senden und die beide aus einer Suche stammen. Sie liefert die Anzeige, ihren Werbetreibenden und die Transparenzdaten, die die Bibliothek für sie veröffentlicht.
adenthält die Felder einer Suchanzeige sowie den Text aus der Vorschau der Anzeige:title,body,ctaText,displayUrl,linkUrl,longTitle,channelName,addressundmerchant, jeweils wo die Anzeige es hat, undvideos(url,previewUrl).previewKindnennt die Art der Anzeige:text(Search),local(Maps, mitaddress),display(Display und YouTube) odershopping(mitmerchant).previewTextlistet die Texte der Vorschau, undpreviewUrlöffnet sie.reachedCountrieslistet die Länder, in denen die Anzeige ausgespielt wurde, als ISO-Codes.impressions(min,max) ist die Impressionen-Spanne, die die Bibliothek für in der EU ausgespielte Anzeigen veröffentlicht. Außerhalb der EU ist sienull.advertiserenthältadvertiserId,advertiserNameundlibraryUrl.transparencyenthältstartDate,endDateundimpressionsder Anzeige, ihresurfaces(surfaceIdund die Impressionen-Spanne jeder Google-Oberfläche;platformnennt eine Oberfläche nur, wo sie bekannt ist:SEARCHundMAPS) und ihrecountries, jeweils mit eigenenstartDate,endDate,impressionsundsurfaces. Bei einer außerhalb der EU ausgespielten Anzeige listettransparencydie Länder mit ihrem letzten Ausspielungstag, und die Daten und Impressionen, die die Bibliothek nur für die EU liefert, sind dortnull(das eigenestartDateder Anzeige wird stattdessen aus der Anzeigenliste gelesen).variantslistet die Darstellungen der Anzeige, die die Bibliothek aufbewahrt:width,height,imageUrlundpreviewUrl.platformsundtargetingsindnull, weil die Bibliothek kein Targeting veröffentlicht.- Eine
libraryId, zu der die Bibliothek keine Anzeige hat, schlägt mitPAGE_UNAVAILABLEfehl.
Preis
Eine Suche reserviert 0.5 Credits je 30 Anzeigen, die ihrlimit verlangt, und berechnet 0.5 Credits je 30 gelieferte Anzeigen, mindestens 0.5 Credits. Die Standardsuche mit 30 Anzeigen kostet 0.5 Credits, und eine Suche mit limit 500 reserviert 8.5 Credits. advertisers und ad kosten je 0.5 Credits. Nur abgeschlossene Anfragen werden berechnet.