# Google Ads Transparency Center Scraper — Ads by Advertiser (`vulcandata/google-ads-transparency`) Actor

Extract ads from Google's Ads Transparency Center for any advertiser or domain: ad ID, format (text/image/video), first/last shown, preview and image URLs, region, and optional EU impression ranges, platforms, topic and audience selection. Filter by country, format, platform, date and political ads.

- **URL**: https://apify.com/vulcandata/google-ads-transparency.md
- **Developed by:** [Sergey Lutsak](https://apify.com/vulcandata) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.40 / 1,000 ads

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Center Scraper — Ads by Advertiser or Domain

Extract every ad an advertiser runs on Google — Search, YouTube, Display, Maps, Play and Shopping — from the official **Google Ads Transparency Center**, as clean JSON. Search by **advertiser name**, **advertiser ID**, **website domain** or a Transparency Center URL; filter by **country**, **format** (text / image / video), **platform**, **date range** and **political ads**. Optionally pull each ad's detail record with **EU impression ranges per country and platform**, **topic** and **audience-selection** signals. No login, no browser: fast and cheap.

### Use cases

- **Competitive intelligence** — see which creatives a competitor is running right now, how long each has been live (`days_shown`) and where (regions, platforms).
- **Ad-creative research & swipe files** — collect image, text and video ads with preview links for a whole industry (search by domain: `nike.com`, `booking.com`, …).
- **Agencies & brand monitoring** — track a client's or partner's ad footprint over time and by market on a schedule.
- **EU DSA / political-ad research** — impression ranges per EU country and platform, topic labels and audience-selection categories for any ad shown in the EU; political-ads mode for election monitoring.
- **AI agents & datasets** — a stable, documented JSON contract for LLM pipelines and analytics.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `queries` | array of strings | — | Advertiser names (`Nike, Inc.`), advertiser IDs (`AR16735076323512287233`), domains (`nike.com`) or Transparency Center URLs. A name is resolved to the best-matching advertiser: exact name first, otherwise the one with the most ads |
| `maxItems` | integer | 100 | Cap on ads **per query** — you are charged only for ads actually returned |
| `region` | string | `anywhere` | ISO 3166-1 alpha-2 country code (`US`, `GB`, `DE`, `PL`, `IN`, `BR`, …) or `anywhere` |
| `format` | `any` / `text` / `image` / `video` | `any` | Ad format |
| `platform` | `any` / `search` / `youtube` / `maps` / `play` / `shopping` | `any` | Platform. Google tags platforms only for ads shown since Sep 4, 2023 |
| `topic` | `all` / `political` | `all` | Political ads only |
| `dateFrom`, `dateTo` | `YYYY-MM-DD` | — | Only ads shown within the range (Pacific Time, as in the Center) |
| `includeDetails` | boolean | false | Fetch the detail record per ad (variations, topic, audience selection, per-country impressions & platforms). One extra request per ad |
| `proxy` | object | Apify datacenter proxy | Proxy configuration |

```json
{
  "queries": ["nike.com", "AR16735076323512287233", "Booking.com"],
  "maxItems": 200,
  "region": "DE",
  "format": "video",
  "platform": "youtube",
  "includeDetails": true
}
```

### Output (one item = one ad)

```json
{
  "id": "CR01003845904182018049",
  "url": "https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR01003845904182018049?region=PL",
  "advertiser_id": "AR16735076323512287233",
  "advertiser_name": "Nike, Inc.",
  "advertiser_domain": "nike.com",            // only for domain queries
  "format": "IMAGE",                           // TEXT | IMAGE | VIDEO
  "first_shown": "2021-10-25T07:00:00Z",
  "last_shown": "2026-09-29T11:53:01Z",
  "days_shown": 1801,                          // Google's count of days the ad had impressions
  "preview_url": "https://displayads-formats.googleusercontent.com/ads/preview/content.js?client=ads-integrity-transparency&…",
  "image_url": "https://tpc.googlesyndication.com/archive/simgad/11154944259192068658",   // archived image, when Google serves one
  "preview_html": "<img src=\"https://tpc.googlesyndication.com/archive/simgad/…\" height=\"219\" width=\"380\">",
  "region": "PL",
  "query": "AR16735076323512287233",

  // with includeDetails = true:
  "variations_count": 3,
  "variations": [{ "preview_url": "…", "image_url": null, "preview_html": null }],
  "topic": { "id": 166, "name": "Apparel & Accessories", "source": "advertiser" },   // source: advertiser | google
  "audience_selection": { "demographic_info": "included", "geographic_locations": "included", "contextual_signals": "not_used" },
  "regions": [
    { "region": "DE", "region_id": 2276, "impressions_min": 1000, "impressions_max": 2000,
      "first_shown": null, "shown_since": "2023-03-06", "last_shown": "2024-08-27",
      "platforms": [{ "platform": "SHOPPING", "impressions_min": 1000, "impressions_max": 2000 }] }
  ],
  "eu_summary": { "impressions_min": 3000, "impressions_max": 4000, "shown_since": "2023-03-01", "last_shown": "2024-08-27", "platforms": [] }
}
```

Notes:

- `preview_url` is Google's rendered preview (a `content.js` loader used by the Transparency Center itself; open the `url` to view the ad). `image_url` is present when Google serves an archived screenshot instead of a rendered preview (typical for text/Shopping ads).
- Impression ranges and platforms are published by Google for ads shown in the **European Union** only (`impressions_*` are `null` elsewhere). Values are bounds, not exact counts.
- Field names are a stable contract: new fields may be added in minor versions; renames only in a major version (see Changelog).

The run's key-value store record `OUTPUT` holds run statistics: requests, resolved advertisers, match totals per query, blocked/not-found counters and `reason_if_empty`.

### Pricing

Pay only for results: **$2.00 per 1,000 ads**. Platform usage is included — no compute bills, no proxy costs. A run that finds nothing costs (almost) nothing.

Discounts on paid Apify plans:

| Apify plan | Price per 1,000 ads |
|---|---|
| Free plan | $2.00 |
| Starter | $1.80 |
| Scale | $1.60 |
| Business | $1.40 |

Examples (Free plan price):

- all ads of one advertiser in one country (~50) → **$0.10**
- 1,000 ads for a competitor set → **$2.00**
- 10,000 ads across a whole industry → **$20.00**

### Limitations

- Advertiser name search returns the single best match; pass an advertiser ID (`AR…`) to be exact — you can find it in any Transparency Center URL.
- Google exposes at most a few thousand ads per query via pagination; use `region`, `format`, `platform` or dates to slice large advertisers.
- Rendering ad previews to screenshots or extracting YouTube video IDs is not included in this version.

### API & integrations

Run it from code — Python:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("vulcandata/google-ads-transparency").call(run_input={"queries": ["nike.com"], "region": "US", "maxItems": 200})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

…or plain HTTP (returns the dataset items directly):

```bash
curl -X POST "https://api.apify.com/v2/acts/vulcandata~google-ads-transparency/run-sync-get-dataset-items?token=<YOUR_APIFY_TOKEN>" \
  -H "Content-Type: application/json" -d '{"queries": ["nike.com"], "region": "US", "maxItems": 200}'
```

- **No-code:** connect to Make, Zapier, n8n, Google Sheets, Slack or webhooks from the actor's *Integrations* tab.
- **Schedules:** run daily/weekly from *Schedules* and get fresh data automatically.
- **AI agents (MCP):** add `vulcandata/google-ads-transparency` to the Apify MCP server (mcp.apify.com) and let Claude, ChatGPT or Cursor call it as a tool.
- **Exports:** JSON, CSV, Excel, XML, RSS — straight from the dataset.

### FAQ

**Is this legal?** The actor reads only what Google publishes in its public Ads Transparency Center — the same pages anyone can open in a browser. No login, no personal data.

**Can I find all ads that point to a website?** Yes — pass the domain (e.g. `booking.com`). Google returns ads from every advertiser account that promotes that domain.

**How do I get the video of a video ad?** `preview_url` is Google's own preview loader; open `url` to watch the ad in the Transparency Center. Direct video files are not exposed by Google.

**Why do impression ranges show null?** Google publishes impression ranges and platforms only for ads shown in the European Union.

**Can I monitor a competitor every week?** Yes — create a schedule in Apify with the same input and get only fresh data each run (filter by `last_shown`).

### More scrapers by VULCAN

- [Medium Scraper](https://apify.com/vulcandata/medium-scraper)
- [Airbnb Scraper](https://apify.com/vulcandata/airbnb-scraper)
- [Google Hotels Scraper](https://apify.com/vulcandata/google-hotels-scraper)

### Changelog

See `CHANGELOG.md`.

# Changelog

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

# Actor input Schema

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

One entry per line: an advertiser name (e.g. `Nike, Inc.`), an advertiser ID (`AR16735076323512287233`), a website domain (`nike.com`) or an Ads Transparency Center URL. Names are resolved to the best-matching advertiser (exact name first, then the one with the most ads).

## `maxItems` (type: `integer`):

Cap on ads returned for each query. You are charged only for ads actually returned.

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

Country the ads were shown in — ISO 3166-1 alpha-2 code such as `US`, `GB`, `DE`, `PL`, `IN`, `BR` — or `anywhere`.

## `format` (type: `string`):

Ad format: text, image or video.

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

Where the ad was shown. Google only tags platforms for ads shown since Sep 4, 2023; older ads are excluded when a platform is selected.

## `topic` (type: `string`):

All ads, or only ads Google classifies as political.

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

Only ads shown on or after this date (Pacific Time, as in the Transparency Center).

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

Only ads shown on or before this date.

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

Fetch each ad's detail record: all creative variations, topic, audience selection (demographic / geographic / contextual signals) and per-country impression ranges with platforms (EU transparency data). One extra request per ad — slower.

## `proxy` (type: `object`):

Apify Proxy settings. Datacenter proxies are sufficient.

## Actor input object example

```json
{
  "queries": [
    "nike.com",
    "AR16735076323512287233"
  ],
  "maxItems": 100,
  "region": "anywhere",
  "format": "any",
  "platform": "any",
  "topic": "all",
  "includeDetails": false,
  "proxy": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `ads` (type: `string`):

All scraped ads as JSON (also available as CSV, Excel or XML via the dataset API).

## `overview` (type: `string`):

Compact table view: advertiser, format, first/last shown, preview.

# 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",
        "AR16735076323512287233"
    ],
    "region": "anywhere"
};

// Run the Actor and wait for it to finish
const run = await client.actor("vulcandata/google-ads-transparency").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",
        "AR16735076323512287233",
    ],
    "region": "anywhere",
}

# Run the Actor and wait for it to finish
run = client.actor("vulcandata/google-ads-transparency").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",
    "AR16735076323512287233"
  ],
  "region": "anywhere"
}' |
apify call vulcandata/google-ads-transparency --silent --output-dataset

```

## MCP server setup

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

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/Nv0LOKGQa43nGqcSS/builds/gjX2smfN6BHE9KcSG/openapi.json