Name: Google Ads Transparency API: Google Ad Library Data
Brand: unseen-user
SKU: api-unseen-user-google-ads
Availability: InStock
Author: API Market

Unseen User

# Google Ads Transparency API

## Overview

The Google Ads Transparency API returns the public ads an advertiser runs on Google, taken from Google's Ads Transparency Center. You send a brand name, a website domain or a Google advertiser ID to one endpoint, and get back every matching ad across Search, Display, YouTube and Shopping, with headlines, descriptions, images, video links, landing pages, regions and run dates. Each request runs a live scrape at call time, so the data reflects what Google is publishing at that moment. No Google Ads account, login or cookies are needed.

It is built for paid media analysts, agencies, e-commerce teams, brand protection teams and researchers who want competitor ad data as rows rather than clicking through the Transparency Center one ad at a time. Each row in `data` is one ad with its advertiser name and ID, creative ID, format and platform, the richest headline and description among its variations, all image URLs, video details, first and last shown dates, days active, regions, impression ranges where Google publishes them, the full list of creative variations and per-region statistics.

## Features

*   **1 endpoint**: `POST /v1/google-ads` returns ads for one or many advertisers in one call.
*   **Flexible inputs**: Mix brand names, domains, full URLs and Google advertiser IDs (`AR...`) in `advertisers`. Each entry is classified automatically, and brand names are resolved to up to 5 matching advertisers.
*   **Live scrape of the Ads Transparency Center**: Every request collects data at call time. No cookies, login or proxy settings are involved.
*   **All Google surfaces**: Text ads (Search), image ads (Display and Shopping) and video ads (YouTube), with a `platform` filter.
*   **Filters**: Regions, date range, platform and political ads only. With several regions, results are merged and duplicates removed by `creativeId`.
*   **Creative variations**: Every headline and description combination Google records, in `variations[]`, plus `variationsCount`.
*   **Volume control**: Cap ads per advertiser with `maxAdsPerAdvertiser`. One call returns up to 100 rows.
*   **Rate limit**: 2 requests per second on every plan.

## Use Cases

*   **PPC competitive intelligence**: See which Search, Display and YouTube ads competitors run, and which they keep running (high `daysActive`).
*   **Agency competitor reports**: Pull a full ad inventory for a client's competitor list in one call.
*   **E-commerce benchmarking**: Compare creative angles, value propositions and landing pages across a category.
*   **YouTube ad research**: Get video links and landing pages for an advertiser's video ads.
*   **Trademark and brand monitoring**: Find ads that bid on or use your brand name.
*   **New ad tracking**: Call the API on a schedule and compare `creativeId` values to detect newly launched ads.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/unseen-user/google-ads
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Get Google ads for advertisers

Returns the public ads for one or more advertisers as rows in `data`, one row per ad. The response always has the shape `{ "success": true, "data": [...], "meta": {...}, "extras": {...} }`, where `meta` carries the count and run information and `extras` carries the run summary and, when enabled, the AI advertiser summaries. In our test, a 4-ad request for `lululemon.com` returned in about 8 seconds.

**Method:** `POST`

**Endpoint:** `/v1/google-ads`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `advertisers` | body | Advertisers to look up. Each entry can be a brand name (`nike`), a domain (`lululemon.com`), a full URL or a Google advertiser ID (`AR01614014350098432001`). Mix freely. | array of strings | Yes | - | - |
| `maxAdsPerAdvertiser` | body | Maximum ads per advertiser; `0` means every public ad. | integer | No | `200` | 100 rows per call |
| `startDate` | body | Only include ads first shown on or after this date, for example `2026-01-01`. Leave blank for no lower bound. | string | No | - | - |
| `endDate` | body | Only include ads last shown on or before this date. Leave blank for no upper bound. | string | No | - | - |
| `regions` | body | Two-letter country codes such as `US`, `GB` or `DE`. Empty means worldwide. With several regions, ads are pulled per region and merged, with duplicates removed. | array of strings | No | `[]` | - |
| `platform` | body | `all`, `search`, `display` or `youtube`. Classified from ad format: text ads are Search, video ads are YouTube, image ads are Display. Shopping ads appear as Display. | string | No | `all` | - |
| `politicalOnly` | body | Return political ads only. A region is required when this is on. | boolean | No | `false` | - |
| `enableAIAnalysis` | body | Adds a creative angle label (discount, urgency, social proof, feature, brand awareness, problem-solution, testimonial, seasonal) and a keyword list to each ad in `creativeAngle` and `keywords`. Needs `anthropicApiKey`. | boolean | No | `false` | - |
| `anthropicApiKey` | body | Your own Anthropic API key. Needed only for `enableAIAnalysis` or `enableAdvertiserSummary`; that usage is billed to your Anthropic account. | string | No | - | - |
| `enableAdvertiserSummary` | body | Adds a two-paragraph positioning summary and 3 key takeaways for each advertiser, returned in `extras`. One AI call per advertiser. Needs `anthropicApiKey`. | boolean | No | `false` | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/unseen-user/google-ads/v1/google-ads" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertisers":["lululemon.com"],"maxAdsPerAdvertiser":4}'
```

**Example Response (200 OK, abridged to the first of 4 ads):**

```json
{
  "success": true,
  "data": [
    {
      "advertiserName": "lululemon athletica canada inc.",
      "domain": "lululemon.com",
      "format": "image",
      "platform": "display",
      "headline": "lululemon Align Yoga Mat 5mm Made With FSC Certified Rubber - Pink Pearl, One Size",
      "description": "lululemon EU",
      "destinationUrl": null,
      "adText": null,
      "imageUrl": "https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcSEAHIBn-WrwQoFqYgzCcPvsWV-TMZc5wQ40l1gEyR8wVql-gM",
      "images": [
        "https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcSEAHIBn-WrwQoFqYgzCcPvsWV-TMZc5wQ40l1gEyR8wVql-gM",
        "https://encrypted-tbn1.gstatic.com/shopping?q=tbn:ANd9GcR-XPmStKUUxACSh_Z5jMEPIeGFC0_vwZmr1HotTxFTP8ew7hZv",
        "https://encrypted-tbn3.gstatic.com/shopping?q=tbn:ANd9GcSC1GEGABdfqkhsgFTcteuKeRZZeoLbqEAUMp7Ys3pfvuM6vBE"
      ],
      "videoUrl": null,
      "videoId": null,
      "videoDuration": null,
      "finalDestinationUrl": "https://lululemon.com/",
      "firstShown": "2026-02-11T05:02:00.000Z",
      "lastShown": "2026-10-15T21:14:12.000Z",
      "daysActive": 247,
      "regions": "Sweden",
      "impressionsMin": "800000",
      "impressionsMax": "900000",
      "variationsCount": 3,
      "adTransparencyUrl": "https://adstransparency.google.com/advertiser/AR01614014350098432001/creative/CR04270460564796342273",
      "advertiserId": "AR01614014350098432001",
      "creativeId": "CR04270460564796342273",
      "scrapedFrom": "domain: lululemon.com",
      "creativeAngle": null,
      "keywords": null,
      "changeStatus": null,
      "variations": [
        {
          "destinationUrl": null,
          "headline": "lululemon Align Yoga Mat 5mm Made With FSC Certified Rubber - Pink Pearl, One Size",
          "image": "https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcSEAHIBn-WrwQoFqYgzCcPvsWV-TMZc5wQ40l1gEyR8wVql-gM",
          "description": "lululemon EU"
        },
        {
          "destinationUrl": null,
          "headline": "lululemon Backpack Double-Zip Backpack 22L Tech Canvas - Black/Graphite Grey, One Size",
          "image": "https://encrypted-tbn1.gstatic.com/shopping?q=tbn:ANd9GcR-XPmStKUUxACSh_Z5jMEPIeGFC0_vwZmr1HotTxFTP8ew7hZv",
          "description": "lululemon EU"
        },
        {
          "destinationUrl": null,
          "headline": "lululemon Backpack Wunderlust Backpack 25L - Black, One Size",
          "image": "https://encrypted-tbn3.gstatic.com/shopping?q=tbn:ANd9GcSC1GEGABdfqkhsgFTcteuKeRZZeoLbqEAUMp7Ys3pfvuM6vBE",
          "description": "lululemon EU"
        }
      ],
      "creativeRegionsDetail": [
        {
          "regionCode": "SE",
          "regionName": "Sweden"
        }
      ],
      "regionStats": [
        {
          "regionCode": "SE",
          "regionName": "Sweden",
          "firstShown": "2026-02-10T00:00:00.000Z",
          "lastShown": "2026-10-15T00:00:00.000Z",
          "impressions": {
            "lower": "800000",
            "upper": "900000"
          },
          "platformImpressions": [
            {
              "platform": "google_search",
              "impressions": {
                "lower": "800000",
                "upper": "900000"
              }
            },
            {
              "platform": "youtube",
              "impressions": {
                "lower": "35000",
                "upper": "40000"
              }
            },
            {
              "platform": "google_shopping",
              "impressions": {
                "upper": "1000"
              }
            }
          ]
        }
      ]
    }
  ]
}
```

**Main fields in each ad row:**

*   **Advertiser**: `advertiserName`, `domain`, `advertiserId`, `scrapedFrom` (which input produced the row).
*   **Format**: `format` (`text`, `image` or `video`) and `platform` (`search`, `display` or `youtube`).
*   **Copy**: `headline`, `description`, `destinationUrl`, `finalDestinationUrl`, and `adText` (text read from the creative, often null for video and carousel ads).
*   **Media**: `imageUrl`, `images[]`, and for video ads `videoUrl`, `videoId` and `videoDuration`.
*   **Timing**: `firstShown`, `lastShown`, `daysActive`.
*   **Reach**: `regions`, `regionStats[]` with per-region dates and impression ranges, `impressionsMin` and `impressionsMax` where Google publishes them.
*   **Variations**: `variationsCount` and `variations[]` with each headline, description, image and destination.
*   **Links**: `adTransparencyUrl` (the ad's page in the Transparency Center) and `creativeId`.

Every field is present on every row. A field is `null` when Google did not publish that piece for that ad, for example images on text Search ads.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request ran and the ads are in `data`. |
| 400 | Bad Request | The body is invalid: `advertisers` is missing or a field has a value outside its allowed options, such as `politicalOnly` without a region. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path is wrong. Use `POST /v1/google-ads`. |
| 429 | Too Many Requests | You went over 2 requests per second, or you used up your plan's request quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 502 | Bad Gateway | The scrape could not be completed. Retry the request. |
| 503 | Service Unavailable | The service is busy or temporarily unavailable. Retry shortly. |
| 504 | Gateway Timeout | The scrape took too long. Calls stop after about 150 seconds; ask for fewer ads and try again. |

## Rate Limits

The Free, Basic, Pro, Ultra and Mega plans all allow 2 requests per second. The Free plan includes 25 requests and stops there; upgrade to a paid plan to keep going. Each request runs a live scrape that took about 8 seconds in our test, so send requests in sequence or with low concurrency. Requests above the limit return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header.

## FAQ

**What can I put in `advertisers`?**

A brand name, a website domain (with or without `https://`), a full URL, or a Google advertiser ID that starts with `AR`. You can mix them in one call. A brand name is treated as a search and resolved to up to 5 matching advertisers; domains and IDs are used directly.

**How do I find an advertiser's Google advertiser ID?**

On a sponsored Google search result, open the menu next to the ad and choose to see more ads from this advertiser. The Ads Transparency Center page that opens has an `AR...` string in its URL. That is the advertiser ID. Every row this API returns also carries it in `advertiserId`.

**Can I see how much an advertiser spent?**

No. Google does not publish spend for commercial ads. Impression ranges appear in `impressionsMin`, `impressionsMax` and `regionStats` when Google publishes them. With `politicalOnly`, the API filters to political ads, but it does not return political spend or demographic fields.

**Can I separate Google Shopping ads from Display ads?**

Not reliably. Shopping product ads come back with `format: "image"` and are classified as `display`, so filtering on `display` returns both.

**How many ads can one call return?**

Up to 100 rows. For an advertiser with more ads, split the work across several calls by region, platform or date range.

**Why are some fields null?**

Google did not publish that field for that ad. Text Search ads have no image, some image creatives have no readable text, and commercial ads usually do not disclose impressions. Text read from image and video creatives can contain small transcription errors, so check `imageUrl` when a field looks wrong.

**Which ads can I not get?**

Only ads Google publishes in the Ads Transparency Center are available. Ads that need a login, age or location restricted ads, and ads removed before Google indexed them cannot be returned.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Google Ads Transparency API that returns an advertiser's public Search, YouTube, Display and Shopping ads with headlines, creatives, run dates and regions.

Google Ads Transparency API: Google Ad Library Data

Free