# Google Ads Transparency API — Real-time Ad Lookup (`foxlabs/google-ads-transparency-api`) Actor

Real-time HTTP API over the Google Ads Transparency Center (ad library). GET /ads with a domain, brand or advertiser ID returns its ads: text (OCR for image-only ads), image, YouTube ID, per-country impressions (EEA/TR), platforms, targeting, topic, Shopping price. Pay per ad.

- **URL**: https://apify.com/foxlabs/google-ads-transparency-api.md
- **Developed by:** [Berkan Kaplan](https://apify.com/foxlabs) (community)
- **Categories:** Marketing, Developer tools, Lead generation
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 ads

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Google Ads Transparency API — Real-time Ad Lookup

A real-time HTTP API over the public [Google Ads Transparency Center](https://adstransparency.google.com/). Send a domain, brand or advertiser ID and get its ads back in seconds: **ad text — read from the ad's picture (OCR) when Google keeps only a picture — image or preview, Shopping price, YouTube video ID, first and last shown date, per-country impressions and platform breakdown (EEA and Turkey), audience-targeting approach, topic** and the **advertiser's legal name**.

This is the Standby (always-on API) edition of [Google Ads Transparency Scraper](https://apify.com/foxlabs/google-ads-transparency-scraper). Same code, same fields, same pricing events. Use this one to call it from your app or agent one query at a time. Use the scraper for large batch jobs, schedules and monitoring.

### Call it

```bash
curl -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  "https://foxlabs--google-ads-transparency-api.apify.actor/ads?query=nike.com&maxAds=10"
```

```bash
curl -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  "https://foxlabs--google-ads-transparency-api.apify.actor/ads?query=Decathlon&region=FR&maxAds=5"
```

```bash
curl -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  "https://foxlabs--google-ads-transparency-api.apify.actor/advertisers?query=hubspot"
```

### Endpoints

#### `GET /ads`

| Parameter | Values | Default |
|---|---|---|
| `query` (required) | Domain (`nike.com`), brand name (`Nike`), advertiser ID (`AR…`) or Transparency Center URL | — |
| `region` | ISO country code (`US`, `DE`, `TR` …) or `anywhere` | anywhere |
| `adFormat` | `all`, `text`, `image`, `video` | all |
| `platform` | `all`, `search`, `youtube`, `maps`, `play`, `shopping` | all |
| `datePreset` | `any`, `last7`, `last30`, `last90`, `last365`, `custom` (+ `dateFrom`, `dateTo` as YYYY-MM-DD; the dates also work on their own, and a fixed period takes precedence over them) | any |
| `maxAds` | 1–100 per request | 40 |
| `maxAdvertisers` | Brand names only: how many of the brand's advertiser entities (1–5) | 1 |
| `includeDetails` | `true` / `false` — regions, impressions, platforms, targeting, topic | true |
| `includeAdCopy` | `true` / `false` — text lines, CTA, display URL, YouTube ID, Shopping title, price and merchant | true |
| `ocr` | `true` / `false` — read the text of ads Google keeps only as a picture (OCR, Latin-script languages); 0.6–7.5 s per picture, depending on how busy the platform's server is | true |

Response: `{ "query", "count", "items": [ … ], "report": { "status", "ads", "totalAdsLow", "totalAdsHigh", "advertisersMatched", "message", "note" }, "dateNote" }`. Each item has the same fields as a dataset row of the scraper. The full list and a sample row are in the scraper's README. `report.note` says when no advertiser carries the exact brand name and the closest match was used; `dateNote` says when a fixed period overrode `dateFrom` / `dateTo`.

Errors: HTTP 400 with `{ "error" }` giving the reason for a missing query, an unknown `region`, `adFormat`, `platform` or `datePreset`, a malformed or reversed date, or a non-numeric `maxAds` / `maxAdvertisers`. HTTP 502 when Google cannot be reached or keeps rate-limiting.

#### `GET /advertisers`

Advertiser accounts matching a name, best match first, with ID, country and ad-count range, plus matching domains. `region` prefers advertisers based in that country. Not billed.

An OpenAPI 3 description of both endpoints is attached to the Actor.

### Measured on the Apify platform (2026-09-23)

| Request | Result | Time |
|---|---|---|
| `/ads?query=nike.com&maxAds=10`, first request (cold start) | 10 ads, all with details | 10.7 s |
| `/ads?query=Decathlon&region=FR&maxAds=5`, warm | 5 ads, matched Decathlon France SASU | 5.4 s |
| `/advertisers?query=hubspot` | 3 advertiser accounts + 10 domains | 1.1 s |

### Pricing

Pay per event, same as the scraper: `ad` for every delivered ad, plus `ad-detail` when details were returned and `ad-copy` when text or other copy fields were read, from the preview or from the ad's picture (OCR). `/advertisers`, requests that return no ads and requests refused with HTTP 400 are not charged. See the Pricing tab.

### Limits and notes

- Up to 100 ads per request. The platform expects the first response within five minutes. For more ads, use the scraper.
- Impressions are published by Google only for the EEA and Turkey, and only for ads that have run there for about three months; new ads have none yet.
- Google keeps many search ads, and most image ads, only as a picture of the ad. With `ocr` on (the default) their text is read from the picture: `adCopyStatus: "ocr"` and `ocrConfidence` (0–100). Pictures that hold no ad are marked `image-placeholder`. Measured: hubspot.com ads with text went from 3.5% to 100 of 100; the scraper's README has coverage, the accuracy review and speed. OCR makes a request slower when many ads are pictures.
- A domain query returns the ads that lead to that domain, whoever runs them; query the `AR…` advertiser ID for one account only.
- Advertiser names are published by Google and can be the names of individuals (sole traders); treat those as personal data where GDPR or similar laws apply.
- Every request needs an Apify API token.
- Not affiliated with Google. The Actor reads the public Ads Transparency Center, whose web interface can change.

### Changelog

#### 0.1.9 — 2026-09-26

Same code as the scraper's 0.1.13: the text of ads Google keeps only as a picture is read by OCR (`ocr=true` by default), with `adCopyStatus: "ocr"` and `ocrConfidence`; pictures that hold no ad are marked `image-placeholder`. See CHANGELOG.md.

#### 0.1.8 — 2026-09-26

Same code as the scraper's 0.1.9, before publication: invalid parameters (unknown region, format, platform or date preset, malformed dates, non-numeric `maxAds`) are answered with HTTP 400 and the reason instead of being dropped; `dateFrom` / `dateTo` work on their own; Shopping items get `price` and `merchantName` no longer holds prices; creative URLs keep the YouTube ID; icons and invisible characters are no longer reported as ad content. See CHANGELOG.md.

#### 0.1 — 2026-09-23

First version. See CHANGELOG.md.

# Changelog

This Actor's version history is a separate document: https://apify.com/foxlabs/google-ads-transparency-api/changelog.md

# Actor input Schema

## `queries` (type: `array`):

One per line. A website domain (nike.com) finds the ads that lead to it, whoever runs them. A brand name (Nike) is matched to the advertiser with that name, or the closest one. An advertiser ID (AR…) or an Ads Transparency Center advertiser/creative URL is used as is.

## `region` (type: `string`):

Only ads shown in this country. "Anywhere" returns ads from every region. Impression counts are published by Google for the EEA and Turkey only.

## `adFormat` (type: `string`):

Text ads include Shopping product ads. Image ads carry their text inside the picture.

## `platform` (type: `string`):

Where the ad was shown.

## `datePreset` (type: `string`):

Only ads that were shown at some point in this period (filter applied by Google).

## `dateFrom` (type: `string`):

Start date, format YYYY-MM-DD. Used when "Shown during" is "Custom dates below" or "Any time"; a fixed period such as "Last 30 days" takes precedence.

## `dateTo` (type: `string`):

End date, format YYYY-MM-DD. Used when "Shown during" is "Custom dates below" or "Any time"; a fixed period such as "Last 30 days" takes precedence.

## `maxAdsPerQuery` (type: `integer`):

Stop after this many ads for each query. Large advertisers have tens of thousands. The form starts at 10 for a quick first run; an API call without this field gets 100.

## `maxAdvertisersPerQuery` (type: `integer`):

For brand-name queries only: how many matching advertiser accounts to include (best match first). A brand often runs ads from several legal entities.

## `includeDetails` (type: `boolean`):

One extra request per ad. Adds first/last shown per country, impression ranges and platform breakdown (EEA and Turkey), audience-targeting approach, topic and variation count.

## `includeAdCopy` (type: `boolean`):

Reads the ad preview: text lines, call to action, display URL, YouTube video ID, Shopping product title, price and merchant, and the landing URL when the preview has one. Ads that Google keeps only as a picture (most image ads and many search ads) are read by the option below.

## `ocrImageAds` (type: `boolean`):

Google keeps many ads only as a picture. With this on, the text in the picture is read (OCR) into the text fields, with adCopyStatus "ocr" and an ocrConfidence score. Latin-script languages: English, German, French, Spanish, Portuguese, Italian, Dutch, Polish, Turkish. Needs "Ad copy" on; counted as ad copy.

## `includeAdvertiserDetails` (type: `boolean`):

Adds the advertiser's legal name, billing country and, where Google publishes it, the D-U-N-S number.

## `onlyNewAds` (type: `boolean`):

Monitoring mode for scheduled runs: returns only ads this monitor has not returned before. A run sees at most "Max ads per query" ads, so combine it with a "Shown during" period (e.g. last 7 days) that the first run can fully cover.

## `monitorName` (type: `string`):

Keeps separate memories for separate monitors (for example one per client). Stored in your own key-value store.

## `proxyConfiguration` (type: `object`):

Not needed for most runs. Leave off and the Actor switches to Apify residential proxy by itself if Google rate-limits it.

## `autoProxyFallback` (type: `boolean`):

When Google answers "too many requests", continue through Apify residential proxy instead of failing.

## Actor input object example

```json
{
  "queries": [
    "nike.com"
  ],
  "region": "anywhere",
  "adFormat": "all",
  "platform": "all",
  "datePreset": "any",
  "maxAdsPerQuery": 10,
  "maxAdvertisersPerQuery": 1,
  "includeDetails": true,
  "includeAdCopy": true,
  "ocrImageAds": true,
  "includeAdvertiserDetails": true,
  "onlyNewAds": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "autoProxyFallback": true
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "queries": [
        "nike.com"
    ],
    "maxAdsPerQuery": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("foxlabs/google-ads-transparency-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "queries": ["nike.com"],
    "maxAdsPerQuery": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("foxlabs/google-ads-transparency-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "queries": [
    "nike.com"
  ],
  "maxAdsPerQuery": 10
}' |
apify call foxlabs/google-ads-transparency-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,foxlabs/google-ads-transparency-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/gKhczGSEQFtw3eoR9/builds/IbdenkipJMsrTcASZ/openapi.json