taskType ADS with platform google_ads_transparency, and action picks what to read. The library covers ads on Google Search, YouTube, Display, Google Play, Maps and Shopping in every country. To choose between the ad libraries, see Ad libraries compared.
search(default) lists the ads of an advertiser withadvertiserId, of several competitors at once withadvertiserIds, or of every advertiser whose ads link to a website withdomain. Each ad carries its format, its first and last shown day and how many days it ran, and the response ends with asummaryof the ads it returned.advertisersfinds an advertiser’sadvertiserIdby name.adopens one ad: its text, video and landing page, and where the library publishes it, the impressions by country and by Google surface.
advertisers and ad cost 0.5 credits each.
Request
GET /v1/async/task/{id} or receive its webhook. See Async tasks.
Analyze a competitor’s ads
Four requests cover a competitor analysis:advertiserswith the competitor’s name returns itsadvertiserIdand the websites the library suggests for the name.searchwith thatadvertiserId, or with the competitor’sdomain, lists its ads.activeDaysshows which ads have run the longest,mediaTypeandpublisherPlatformssplit the ads by creative and surface, andsummarycounts the formats and the ads that started in each week.adwith an ad’slibraryIdandadvertiserIdreturns its text, video, the countries it reached and, for ads shown in the EU, its impressions by country and surface.searchwithadvertiserIdscompares up to 10 competitors in one request.
Parameters
action:search(default),advertisersorad.query: An advertiser’s name, 1 to 100 characters.advertisersrequires it, andsearchandadreject it.advertiserId: An advertiser’s ID, such asAR16396071307843731457.searchneedsadvertiserId,advertiserIdsordomain, andadrequiresadvertiserId.advertiserIds: 1 to 10 advertiser IDs, as an array or comma-separated text. SendadvertiserIdsoradvertiserIdin one request.domain: A bare domain such asnike.com.searchlists the ads that link to it, whichever advertiser runs them.domainand the advertiser IDs exclude each other.libraryId: An ad’s creative ID, such asCR07264436911983296513.adrequires it.country: Where the ads were shown, as a two-letter country code, orALLfor every country (default). One country at a time.searchreads it.publisherPlatforms: Where the ads ran:search,youtube,maps,shoppingorplay. One value at a time.mediaType:all(default),text,imageorvideo.startDate,endDate:YYYY-MM-DD, sent together. Keeps the ads shown at least once between the two days.limit: 1 to 500 ads onsearch(default 30), 1 to 50 advertisers onadvertisers(default 30).cursor: ThenextCursorof an earlier response, to read the ads after it.
search reads advertiserId, advertiserIds, domain, country, publisherPlatforms, mediaType, startDate, endDate, limit and cursor. advertisers reads query and limit, and ad reads advertiserId and libraryId. A field the library cannot search, such as pageId, activeStatus or sortBy, or a field the action does not read, is rejected with 400 VALIDATION_ERROR, and details names the field.
Compare competitors
advertiserIds lists the ads of up to 10 advertisers in one request. The summary of the response counts the ads of each advertiser, so one request shows who runs the most ads.
Read more ads
A page of the library holds up to 100 ads, so alimit above 100 reads several pages in one request. A response with more ads to read carries nextCursor. Send it as cursor with the same search to receive the next ads, again up to limit. nextCursor is null once the library has no more.
A cursor works only with the search that returned it: a different advertiserId, advertiserIds, domain, country, publisherPlatforms, mediaType or date range is rejected with 400 VALIDATION_ERROR, while limit can change.
Find an advertiser
action advertisers returns the advertisers whose names match query, as the library’s search box suggests them. Send the advertiserId you pick to search that advertiser’s ads.
advertiserId, advertiserName, country (where the advertiser is registered), verified, adCountRange (the library’s range of the advertiser’s ads, min and max) and libraryUrl, which opens the advertiser in the Transparency Center. adCount is null because the library gives a range. domains lists the websites the library suggests for the name, which search takes as domain. A name no advertiser carries completes with an empty advertisers. An advertiser search takes only query and limit, and costs 0.5 credits.
Search response
- The response echoes
platform,action,country,advertiserId,advertiserIdsordomain, and the filters it was given. totalCountRangeis the library’s estimate of the matching ads, as aminandmax.totalCountisnull.returnedCountcounts the ads inads,hasMoreistruewhen the library has more, whichnextCursorreads, andlibraryUrlopens the same search in the Transparency Center.- Each ad has
position,libraryId,libraryUrl,advertiserId,advertiserName,format(TEXT,IMAGEorVIDEO),width,height,images,videos,startDate,endDate,activeDays,isActiveandlandingDomain. startDateandendDateare the first and last day the library shows the ad (days in UTC).activeDayscounts the days fromstartDatetoendDate, both counted, and isnullwhen the library gives nostartDate.isActiveistruefor an ad last shown today or yesterday, because the library publishes the last time an ad was shown and not whether it runs.landingDomainis the host of the ad’s landing page, in lowercase withoutwww., andnullwhere the library gives none.- Many text ads arrive as an image:
imagesholds a link to the ad as the library draws it, and the text is inad.title,body,ctaTextandlinkUrlarenullin a search and filled byadwhere the ad’s preview has them.impressionsis filled byadfor ads shown in the EU.platforms,targeting,payerandutmarenull. summarycounts the ads of this response:ads,activeAds,advertisers(the 10 with the most ads:advertiserId,advertiserName,ads),formats,landingDomains(the 10 with the most ads),oldestStartDate,newestStartDateandmedianActiveDays. It also haslaunchesByWeek(the ads that started in each ISO week, oldest week first) andlongestRunning(the 5 ads with the mostactiveDays). A search withlimit500 summarizes 500 ads, and each page you read withcursorcarries the summary of its own ads.- Image links of ads (
tpc.googlesyndication.com) are not signed and stay open. The preview links ofadare signed and can expire. - A search with no matching ads completes with an empty
adsand asummaryof0ads.
What the library keeps
- The library shows ads of every country. An ad stays about 12 months after the last day it was shown.
- Ads shown in the EU carry impressions: a range for the ad, for each country with its first and last shown day, and for each Google surface. Ads shown elsewhere carry the countries the ad reached and the last shown day. For those,
adreads the first shown day (andactiveDays) from the advertiser’s ad list, the same valuesearchreturns, and leavesstartDateandactiveDaysnullonly if the ad is not among the list’s first 800 ads for the country it reached;debug.datesisdetail,searchornot-found.
Open one ad
action ad opens the ad with the libraryId and advertiserId you send, both from a search. It returns the ad, its advertiser and the transparency the library publishes for it.
adhas the fields of a search ad, plus the text from the ad’s preview:title,body,ctaText,displayUrl,linkUrl,longTitle,channelName,addressandmerchant, each where the ad has it, andvideos(url,previewUrl).previewKindnames the kind of the ad:text(Search),local(Maps, withaddress),display(Display and YouTube) orshopping(withmerchant).previewTextlists the texts of the preview, andpreviewUrlopens it.reachedCountrieslists the countries the ad was shown in, as ISO codes.impressions(min,max) is the range of impressions the library publishes for ads shown in the EU. Outside the EU it isnull.advertiserhasadvertiserId,advertiserNameandlibraryUrl.transparencycarries the ad’sstartDate,endDateandimpressions, itssurfaces(surfaceIdand the impressions range of each Google surface;platformnames a surface only where it is known:SEARCHandMAPS) and itscountries, each with its ownstartDate,endDate,impressionsandsurfaces. For an ad shown outside the EU,transparencylists the countries with their last shown day, and the dates and impressions that the library gives only for the EU arenullthere (the ad’s ownstartDateis read from the ad list instead).variantslists the renderings of the ad the library keeps:width,height,imageUrlandpreviewUrl.platformsandtargetingarenull, because the library publishes no targeting.- A
libraryIdthe library has no ad for fails withPAGE_UNAVAILABLE.
Price
A search holds 0.5 credits for every 30 ads itslimit asks for, and is charged 0.5 credits for every 30 ads it returns, at least 0.5 credits. The default search of 30 ads costs 0.5 credits, and a search with limit 500 holds 8.5 credits. advertisers and ad cost 0.5 credits each. Only completed requests are charged.