API reference

Google Ads Transparency Center: GET /v1/google/ads

Search one advertiser's ads in the Google Ads Transparency Center (Search, YouTube, Shopping, Maps and Play) by its advertiser id or verified domain, filtered by country, format, surface and political ads.

Ads a pageup to 100One page per call; next_cursor for more.

Credits1 credit a pageOnly when the page has ads. Empty pages, errors and the sandbox are free.

CoversEvery country Google runs ads inSearch by advertiser_id or domain.

Request

curl "https://api.publicadsapi.com/v1/google/ads?domain=tailspin-travel.example&country=GB" \
  -H "authorization: Bearer $PADS_API_KEY"

Parameters

Every filter here is the library's own, run by the platform, so pages are full and total_estimate counts what matches. Anything else is 400 INVALID_INPUT naming it.

Authorizationstringheaderrequired

Bearer <key>. Keys starting pads_test_ get the sandbox (sample ads, never charged); keys starting pads_live_ read the platform and use credits.

advertiser_idstringquerysend one of advertiser_id, domain

Google's advertiser id: AR and digits, as in the advertiser's Transparency Center address.

Example: advertiser_id=AR10000000000000000001

domainstringquerysend one of advertiser_id, domain

The advertiser's verified domain, such as example.com. An advertiser that verified under another domain returns no ads for this one: try its advertiser_id.

Example: domain=tailspin-travel.example

countrystringquery

Where the ad was shown: an ISO 3166-1 alpha-2 code, or ALL. Two letters that are no country (ZZ) are refused. Default ALL. Also accepted as country_code.

Example: country=GB

formatstringquery

Left out: every format. Text ads come back as an image in media; their text may be null (text_source: "ocr" where it was read from the image). One of: text, image, video. Also accepted as media_type.

surfacestringquery

Where on Google the ad ran. Left out: everywhere. One of: search, youtube, shopping, maps, play.

politicalbooleanquery

true: political ads only. Needs a country, as Google lists political ads per country. Default false.

date_fromYYYY-MM-DDquery

Ads shown on or after this day, YYYY-MM-DD.

Example: date_from=2026-01-01

date_toYYYY-MM-DDquery

Ads shown on or before this day, YYYY-MM-DD. Not before date_from.

Example: date_to=2026-10-21

cursorstringquery

The next_cursor of the page before. Send it with exactly the same other parameters: a cursor from a different search is 400 INVALID_INPUT.

includecomma-separatedquery

raw adds each ad's own record from the platform as raw, for fields we don't map. Values: raw.

Example: include=raw

Response

200 OK (sandbox; the first ad of the page)

{
  "platform": "google",
  "query": {
    "advertiser_id": null,
    "domain": "tailspin-travel.example",
    "country": "GB",
    "format": null,
    "surface": null,
    "political": false,
    "date_from": null,
    "date_to": null
  },
  "ads": [
    {
      "id": "google_AR10000000000000000001_CR20000000000000000001",
      "platform": "google",
      "platform_ad_id": "CR20000000000000000001",
      "library_url": "https://adstransparency.google.com/advertiser/AR10000000000000000001/creative/CR20000000000000000001",
      "advertiser": {
        "id": "AR10000000000000000001",
        "name": "Tailspin Travel Ltd",
        "domain": "tailspin-travel.example",
        "library_url": "https://adstransparency.google.com/advertiser/AR10000000000000000001"
      },
      "status": "unknown",
      "first_shown": "2025-10-13T00:00:00Z",
      "last_shown": "2026-10-18T00:00:00Z",
      "format": "text",
      "text": {
        "headline": "Tailspin Travel | City breaks from £99",
        "body": "Flights and hotel together. ATOL protected. Book by Sunday.",
        "description": null,
        "cta": null
      },
      "text_source": "ocr",
      "link_url": "https://tailspin-travel.example/city-breaks",
      "media": [
        {
          "type": "image",
          "url": "https://example.com/sandbox-media/google-text.png",
          "preview_url": null,
          "width": 380,
          "height": 120
        }
      ],
      "placements": [
        "search"
      ],
      "regions": [
        "GB",
        "DE",
        "IE"
      ],
      "metrics": {
        "impressions": null,
        "reach": null,
        "spend": null
      },
      "variants": 4
    }
  ],
  "total_estimate": 4,
  "has_more": true,
  "next_cursor": "eyJwIjoiZ29vZ2xlIiwiYyI6IjMiLCJxIjoidjNNaXRtc2dDcWlNR3BjWSJ9",
  "credits_used": 0,
  "credits_remaining": null
}

What Google ads carry

advertiser.id is Google's AR… id and advertiser.domain its verified domain.
status is always unknown: Google gives the first and last days an ad was shown, not whether it is running. Compare last_shown with today.
Text ads are shown by Google only as an image, which is in media. Their text may be null: where we have read the words off the image, text_source is ocr.
regions lists the countries Google says the ad ran in. variants is how many versions Google holds.
metrics is null in search. Impressions by country are in the detail, for ads shown in the EU.

Limits to know

Google's library has no keyword search: search by advertiser_id or domain. To find an advertiser's id, take it from an ad's advertiser.id, or from its page's address in the Transparency Center (adstransparency.google.com/advertiser/AR…).
Some advertisers verify under a domain other than their website's. An empty answer for a domain is genuine for that domain: try the advertiser's advertiser_id.
Google returns up to 100 ads a page, quickly: Google is the fastest of the four.
Ads shown in the US come with dates and the ad itself; impressions and targeting are given for ads shown in the EU, and for political ads.

One ad with its detail

GET /v1/ads/{id} with an id from this search (1 credit). Every version of the ad and each country it ran in with the days it was first and last shown. For ads shown in the EU, also impressions ranges per country, which kinds of targeting were used (demographics, location, contextual, customer lists) and who paid. An ad shown only in the UK gives its countries and the day it was last shown. See One ad.