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

Base URL: `https://api.publicadsapi.com` · Auth: `authorization: Bearer <key>` · Web version: https://publicadsapi.com/docs/api/google

- **Ads a page**: up to 100. One page per call; `next_cursor` for more.
- **Credits**: 1 credit a page. Only when the page has ads. Empty pages, errors and the sandbox are free.
- **Covers**: Every country Google runs ads in. Search by `advertiser_id` or `domain`.

## Request

cURL:

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

Node.js:

```js
const res = await fetch('https://api.publicadsapi.com/v1/google/ads?domain=tailspin-travel.example&country=GB', {
  headers: { authorization: `Bearer ${process.env.PADS_API_KEY}` },
});

const result = await res.json();
if (!res.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result.ads.length, 'ads; next page:', result.next_cursor);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://api.publicadsapi.com/v1/google/ads?domain=tailspin-travel.example&country=GB",
    headers={"authorization": f"Bearer {os.environ['PADS_API_KEY']}"},
    timeout=60,
)
result = res.json()
if not res.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(len(result["ads"]), "ads; next page:", result["next_cursor"])
```

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

- `Authorization` (header, string, required): `Bearer <key>`. Keys starting `pads_test_` get the sandbox (sample ads, never charged); keys starting `pads_live_` read the platform and use credits.
- `advertiser_id` (query, string, send one of advertiser_id, domain): Google's advertiser id: `AR` and digits, as in the advertiser's Transparency Center address. Example: `advertiser_id=AR10000000000000000001`
- `domain` (query, string, send 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`
- `country` (query, string): 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`
- `format` (query, string): 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`.
- `surface` (query, string): Where on Google the ad ran. Left out: everywhere. One of: `search`, `youtube`, `shopping`, `maps`, `play`.
- `political` (query, boolean): `true`: political ads only. Needs a `country`, as Google lists political ads per country. Default `false`.
- `date_from` (query, YYYY-MM-DD): Ads shown on or after this day, `YYYY-MM-DD`. Example: `date_from=2026-01-01`
- `date_to` (query, YYYY-MM-DD): Ads shown on or before this day, `YYYY-MM-DD`. Not before `date_from`. Example: `date_to=2026-10-21`
- `cursor` (query, string): 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`.
- `include` (query, comma-separated): `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):

```json
{
  "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](https://publicadsapi.com/docs/api/ads.md).

See also: [Meta](https://publicadsapi.com/docs/api/meta.md) · [TikTok](https://publicadsapi.com/docs/api/tiktok.md)