Skip to main content
Read the Google Ads Transparency Center as JSON through the async task API, to see which Google ads your competitors run. ADS is its own engine: send 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 with advertiserId, of several competitors at once with advertiserIds, or of every advertiser whose ads link to a website with domain. Each ad carries its format, its first and last shown day and how many days it ran, and the response ends with a summary of the ads it returned.
  • advertisers finds an advertiser’s advertiserId by name.
  • ad opens one ad: its text, video and landing page, and where the library publishes it, the impressions by country and by Google surface.
A search costs 0.5 credits for every 30 ads it returns. advertisers and ad cost 0.5 credits each.

Request

Submit the task, then poll GET /v1/async/task/{id} or receive its webhook. See Async tasks.

Analyze a competitor’s ads

Four requests cover a competitor analysis:
  1. advertisers with the competitor’s name returns its advertiserId and the websites the library suggests for the name.
  2. search with that advertiserId, or with the competitor’s domain, lists its ads. activeDays shows which ads have run the longest, mediaType and publisherPlatforms split the ads by creative and surface, and summary counts the formats and the ads that started in each week.
  3. ad with an ad’s libraryId and advertiserId returns its text, video, the countries it reached and, for ads shown in the EU, its impressions by country and surface.
  4. search with advertiserIds compares up to 10 competitors in one request.

Parameters

  • action: search (default), advertisers or ad.
  • query: An advertiser’s name, 1 to 100 characters. advertisers requires it, and search and ad reject it.
  • advertiserId: An advertiser’s ID, such as AR16396071307843731457. search needs advertiserId, advertiserIds or domain, and ad requires advertiserId.
  • advertiserIds: 1 to 10 advertiser IDs, as an array or comma-separated text. Send advertiserIds or advertiserId in one request.
  • domain: A bare domain such as nike.com. search lists the ads that link to it, whichever advertiser runs them. domain and the advertiser IDs exclude each other.
  • libraryId: An ad’s creative ID, such as CR07264436911983296513. ad requires it.
  • country: Where the ads were shown, as a two-letter country code, or ALL for every country (default). One country at a time. search reads it.
  • publisherPlatforms: Where the ads ran: search, youtube, maps, shopping or play. One value at a time.
  • mediaType: all (default), text, image or video.
  • startDate, endDate: YYYY-MM-DD, sent together. Keeps the ads shown at least once between the two days.
  • limit: 1 to 500 ads on search (default 30), 1 to 50 advertisers on advertisers (default 30).
  • cursor: The nextCursor of 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 a limit 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.
Each advertiser has 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, advertiserIds or domain, and the filters it was given.
  • totalCountRange is the library’s estimate of the matching ads, as a min and max. totalCount is null. returnedCount counts the ads in ads, hasMore is true when the library has more, which nextCursor reads, and libraryUrl opens the same search in the Transparency Center.
  • Each ad has position, libraryId, libraryUrl, advertiserId, advertiserName, format (TEXT, IMAGE or VIDEO), width, height, images, videos, startDate, endDate, activeDays, isActive and landingDomain.
  • startDate and endDate are the first and last day the library shows the ad (days in UTC). activeDays counts the days from startDate to endDate, both counted, and is null when the library gives no startDate. isActive is true for an ad last shown today or yesterday, because the library publishes the last time an ad was shown and not whether it runs.
  • landingDomain is the host of the ad’s landing page, in lowercase without www., and null where the library gives none.
  • Many text ads arrive as an image: images holds a link to the ad as the library draws it, and the text is in ad. title, body, ctaText and linkUrl are null in a search and filled by ad where the ad’s preview has them. impressions is filled by ad for ads shown in the EU. platforms, targeting, payer and utm are null.
  • summary counts 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, newestStartDate and medianActiveDays. It also has launchesByWeek (the ads that started in each ISO week, oldest week first) and longestRunning (the 5 ads with the most activeDays). A search with limit 500 summarizes 500 ads, and each page you read with cursor carries the summary of its own ads.
  • Image links of ads (tpc.googlesyndication.com) are not signed and stay open. The preview links of ad are signed and can expire.
  • A search with no matching ads completes with an empty ads and a summary of 0 ads.

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, ad reads the first shown day (and activeDays) from the advertiser’s ad list, the same value search returns, and leaves startDate and activeDays null only if the ad is not among the list’s first 800 ads for the country it reached; debug.dates is detail, search or not-found.
To keep a competitor’s ad history, search its ads on a schedule, for example every day, and store them.

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.
  • ad has the fields of a search ad, plus the text from the ad’s preview: title, body, ctaText, displayUrl, linkUrl, longTitle, channelName, address and merchant, each where the ad has it, and videos (url, previewUrl). previewKind names the kind of the ad: text (Search), local (Maps, with address), display (Display and YouTube) or shopping (with merchant). previewText lists the texts of the preview, and previewUrl opens it.
  • reachedCountries lists 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 is null.
  • advertiser has advertiserId, advertiserName and libraryUrl.
  • transparency carries the ad’s startDate, endDate and impressions, its surfaces (surfaceId and the impressions range of each Google surface; platform names a surface only where it is known: SEARCH and MAPS) and its countries, each with its own startDate, endDate, impressions and surfaces. For an ad shown outside the EU, transparency lists the countries with their last shown day, and the dates and impressions that the library gives only for the EU are null there (the ad’s own startDate is read from the ad list instead).
  • variants lists the renderings of the ad the library keeps: width, height, imageUrl and previewUrl.
  • platforms and targeting are null, because the library publishes no targeting.
  • A libraryId the library has no ad for fails with PAGE_UNAVAILABLE.

Price

A search holds 0.5 credits for every 30 ads its limit 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.