> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Ads Transparency API

> Analyze competitor ads from the Google Ads Transparency Center as JSON: list the Search, YouTube, Display, Play, Maps and Shopping ads an advertiser runs with how long each ran, and open one ad for its text, video and impressions by country.

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](https://docs.querying.ai/engines/ad-libraries.md).

* `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

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "google_ads_transparency", "domain": "nike.com", "country": "KR", "limit": 5 } }'
```

Submit the task, then poll `GET /v1/async/task/{id}` or receive its webhook. See [Async tasks](https://docs.querying.ai/concepts/async-tasks.md).

## 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.

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "google_ads_transparency", "advertiserIds": ["AR16396071307843731457", "<competitor advertiserId>"], "country": "KR", "mediaType": "video" } }'
```

## 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.

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "google_ads_transparency", "action": "advertisers", "query": "올리브영" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "google_ads_transparency",
  "action": "advertisers",
  "query": "올리브영",
  "returnedCount": 10,
  "libraryUrl": "https://adstransparency.google.com/?region=anywhere",
  "advertisers": [
    {
      "libraryUrl": "https://adstransparency.google.com/advertiser/AR16396071307843731457?region=anywhere",
      "advertiserId": "AR16396071307843731457",
      "advertiserName": "CJ올리브영",
      "country": "KR",
      "verified": false,
      "adCount": null,
      "adCountRange": { "min": 800, "max": 900 }
    }
  ],
  "domains": []
}
```

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

```json theme={"theme":"css-variables"}
{
  "platform": "google_ads_transparency",
  "action": "search",
  "country": "KR",
  "domain": "nike.com",
  "totalCount": null,
  "totalCountRange": { "min": 1000, "max": 2000 },
  "returnedCount": 5,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoiZnl5NGtZLXJ2MjBLQkVlcCIsImMiOiJDZ29BUDd6bWZJN0cwNlFURWhDUFRtUGphSW8rNThJRCtROEFBQUFBR2duOCtHUHIrSExRTEM4PSIsInAiOjV9",
  "libraryUrl": "https://adstransparency.google.com/?region=KR&domain=nike.com",
  "ads": [
    {
      "position": 1,
      "libraryId": "CR09172534072340119553",
      "libraryUrl": "https://adstransparency.google.com/advertiser/AR01437837420136497153/creative/CR09172534072340119553?region=anywhere",
      "advertiserId": "AR01437837420136497153",
      "advertiserName": "株式会社ナイキジャパン",
      "isActive": true,
      "startDate": "2025-01-08",
      "endDate": "2026-11-22",
      "activeDays": 684,
      "platforms": null,
      "format": "TEXT",
      "width": 348,
      "height": 517,
      "title": null,
      "body": null,
      "ctaText": null,
      "ctaType": null,
      "linkUrl": null,
      "landingDomain": "nike.com",
      "utm": null,
      "payer": null,
      "impressions": null,
      "targeting": null,
      "reachedCountries": null,
      "images": ["https://tpc.googlesyndication.com/archive/simgad/11407271379265753184"],
      "videos": []
    }
  ],
  "summary": {
    "ads": 5,
    "activeAds": 5,
    "advertisers": [
      { "advertiserId": "AR01437837420136497153", "advertiserName": "株式会社ナイキジャパン", "ads": 3 }
    ],
    "formats": { "TEXT": 5 },
    "platforms": {},
    "ctaTypes": {},
    "landingDomains": [
      { "domain": "nike.com", "ads": 5 }
    ],
    "utmCampaigns": [],
    "launchesByWeek": [
      { "week": "2022-W32", "ads": 1 }
    ],
    "longestRunning": [
      {
        "libraryId": "CR16869261615919267841",
        "advertiserName": "NIKE GLOBAL TRADING B.V. SINGAPORE BRANCH",
        "isActive": true,
        "activeDays": 1563,
        "title": null
      }
    ],
    "oldestStartDate": "2022-08-13",
    "newestStartDate": "2025-01-08",
    "medianActiveDays": 714
  }
}
```

* 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.

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "google_ads_transparency", "action": "ad", "advertiserId": "AR18378488041124659201", "libraryId": "CR16529691107676651521" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "google_ads_transparency",
  "action": "ad",
  "ad": {
    "libraryId": "CR16529691107676651521",
    "libraryUrl": "https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR16529691107676651521?region=anywhere",
    "advertiserId": "AR18378488041124659201",
    "advertiserName": "Nike Retail BV",
    "isActive": true,
    "startDate": "2025-11-18",
    "endDate": "2026-11-22",
    "activeDays": 370,
    "platforms": null,
    "format": "TEXT",
    "title": "Nike Black Friday Days trwają - Rabat do 40% na wybrane modele",
    "body": "Dni Nike Black Friday Days wystartowały. Zniżki do 40% na wybrane produkty. Do 1 grudnia.",
    "ctaText": null,
    "ctaType": null,
    "linkUrl": null,
    "landingDomain": "nike.com",
    "utm": null,
    "payer": null,
    "impressions": { "min": 9000, "max": 10000 },
    "targeting": null,
    "reachedCountries": ["DE", "PL"],
    "images": [],
    "videos": [],
    "displayUrl": "www.nike.com/kobiety/fleece",
    "previewKind": "text",
    "previewText": ["nike.com", "www.nike.com/kobiety/fleece"],
    "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js"
  },
  "advertiser": {
    "libraryUrl": "https://adstransparency.google.com/advertiser/AR18378488041124659201?region=anywhere",
    "advertiserId": "AR18378488041124659201",
    "advertiserName": "Nike Retail BV"
  },
  "transparency": {
    "startDate": "2025-11-18",
    "endDate": "2026-11-22",
    "impressions": { "min": 9000, "max": 10000 },
    "surfaces": [
      {
        "impressions": { "min": 9000, "max": 10000 },
        "surfaceId": 3,
        "platform": "SEARCH"
      },
      {
        "impressions": { "min": 0, "max": 1000 },
        "surfaceId": 2,
        "platform": "MAPS"
      }
    ],
    "countries": [
      {
        "country": "DE",
        "startDate": "2025-11-24",
        "endDate": "2026-11-22",
        "impressions": { "min": 0, "max": 1000 },
        "surfaces": [
          {
            "impressions": { "min": 0, "max": 1000 },
            "surfaceId": 3,
            "platform": "SEARCH"
          }
        ]
      },
      {
        "country": "PL",
        "startDate": "2025-11-18",
        "endDate": "2026-11-22",
        "impressions": { "min": 9000, "max": 10000 },
        "surfaces": [
          {
            "impressions": { "min": 0, "max": 1000 },
            "surfaceId": 2,
            "platform": "MAPS"
          },
          {
            "impressions": { "min": 9000, "max": 10000 },
            "surfaceId": 3,
            "platform": "SEARCH"
          }
        ]
      }
    ]
  },
  "variants": [
    {
      "width": null,
      "height": null,
      "imageUrl": null,
      "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js"
    },
    {
      "width": null,
      "height": null,
      "imageUrl": null,
      "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js"
    }
  ]
}
```

* `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.

## Related

* [Ad libraries compared](https://docs.querying.ai/engines/ad-libraries.md)
* [Meta Ad Library](https://docs.querying.ai/engines/meta-ad-library.md)
* [Engine overview](https://docs.querying.ai/engines/overview.md)
* [Credits and limits](https://docs.querying.ai/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.