# Google Ads Transparency Center Scraper (`datapeak/google-ads-transparency`) Actor

Scrape the Google Ads Transparency Center by advertiser or domain. Extract ad creatives, formats (text/image/video), platforms, regions and run dates as JSON/CSV. Built for competitor ad research, PPC agencies and media buyers. No login, pay per result, one-click or API.

- **URL**: https://apify.com/datapeak/google-ads-transparency.md
- **Developed by:** [Gal Gilboa](https://apify.com/datapeak) (community)
- **Categories:** Lead generation, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 33 total users, 10 monthly users, 91.9% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 ad scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 — Competitor Google Ads, Creatives & Run Dates

Extract structured data from **Google's Ads Transparency Center** (adstransparency.google.com): every ad an advertiser runs across **Google Search, YouTube, Display, Shopping and Maps** — ad format, creative preview URLs, decoded text-ad copy (headline, description, destination URL), first/last shown dates and regions. No login, no API key, public transparency data only.

Built for **media buyers, PPC agencies and competitor-intel teams**: see which Google ads your competitors run, which creatives they keep alive (the winners), and when new campaigns launch — on a schedule, in bulk.

### Why this Actor?

- **API-level reliability** — talks directly to the Transparency Center's own JSON endpoints instead of driving a browser against a JavaScript shell. No brittle CSS selectors, no half-loaded pages, no missing ads.
- **Bulk advertiser lists** — monitor 1 or 100 competitors in a single run: mix domains (`nike.com`), advertiser IDs (`AR…`) and company names freely.
- **Text ads decoded** — Google hides search-ad copy inside encoded preview URLs; this Actor decodes it into clean `headline` / `description` / `destinationUrl` fields.
- **Date intelligence** — first/last shown timestamps per creative, so you can spot long-running (i.e. profitable) ads and diff new launches between scheduled runs.
- **Fast & cheap** — plain HTTP, 256 MB memory, no browser. Hundreds of ads per minute.

### What data does it return?

One dataset item per ad:

- Advertiser name + Google advertiser ID (`AR…`)
- Creative ID (`CR…`) + permanent Transparency Center URL
- Ad format: `text`, `image` or `video`
- Creative preview URLs (image file, video preview, rendered-ad iframe)
- Decoded text-ad copy: headline, description, destination URL
- First shown / last shown dates (ISO timestamps)
- Regions (best-effort, plus your region filter)
- Which query found the ad + scrape timestamp

### Sample output

```json
{
  "type": "ad",
  "advertiserId": "AR14188379519798214657",
  "advertiserName": "Nike, Inc.",
  "creativeId": "CR10813648716908961793",
  "format": "text",
  "headline": "Shop the New Air Max Collection",
  "description": "Free shipping and returns on every order. Find your perfect fit today.",
  "destinationUrl": "nike.com/airmax",
  "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js?...",
  "previewUrls": ["https://displayads-formats.googleusercontent.com/ads/preview/content.js?..."],
  "imageUrl": null,
  "videoUrl": null,
  "firstShownAt": "2025-01-01T00:00:00.000Z",
  "lastShownAt": "2026-01-01T00:00:00.000Z",
  "regions": ["GB", "US"],
  "detailsUrl": "https://adstransparency.google.com/advertiser/AR14188379519798214657/creative/CR10813648716908961793?region=anywhere",
  "query": "domain nike.com",
  "scrapedAt": "2026-07-12T12:00:00.000Z"
}
```

Fields Google doesn't expose for a given ad come back as `null` / `[]` — the Actor never fails a run over a missing field.

### How to use it

| Input | What it does |
|---|---|
| `queries` | **Bulk list** of advertisers — domains (`nike.com`), advertiser IDs (`AR…`, most reliable), Transparency Center URLs, or company names |
| `region` | Two-letter country filter (`US`, `GB`, `IL`, …) or `anywhere` (default). Google enforces this loosely for some advertisers — treat as a hint |
| `maxAdsPerQuery` | Cap per advertiser query (default 100) |
| `fetchAdDetails` | Per-creative lookup for preview URLs, decoded copy, dates and regions (default on) |
| `proxyConfiguration` | Apify RESIDENTIAL proxy recommended for scheduled runs |

**Tip:** the advertiser ID is the `AR…` segment in any adstransparency.google.com URL — grab it once and your scheduled monitoring never depends on name/domain matching.

### Use cases

- **Competitor ad monitoring** — schedule a weekly run over your competitor list; diff creative IDs to catch new campaigns and retired ads automatically.
- **Winning-ad detection** — sort by `firstShownAt`: ads that stay live for months are paying for themselves.
- **Search-ad copy research** — decoded headlines/descriptions for every text ad in your category, ready for a swipe file.
- **Creative swipe file** — image/video preview URLs for competitor display and YouTube ads.
- **Agency reporting** — attach a client-vs-competitor Google Ads snapshot to monthly reports via the API.

### Pricing (pay per event)

| Event | Price | Meaning |
|---|---|---|
| `ad-scraped` | $0.002 | One ad record in the dataset |

Example: monitoring 20 competitors × 100 ads each = 2,000 ads = **$4.00** per run.
The Actor respects your maximum cost per run and stops cleanly when the limit is reached.

### Fair use & limitations

- Only public Ads Transparency Center data is accessed — the same ad-transparency information Google shows any visitor, published by Google specifically for public scrutiny. No login, no personal data.
- Political ads carry extra fields in Google's UI (spend, impressions) that are not extracted in v1.
- Google's region filter is enforced loosely server-side for some advertisers; the `regions` output field is best-effort.
- Video ads return Google's preview URL; final `googlevideo.com` file URLs are short-lived by design.

### Integrations

Standard Apify platform features apply: export to JSON/CSV/Excel, API access, webhooks, and scheduled runs for continuous competitor monitoring.

### Development

```bash
npm install
npm test           # parses the saved RPC fixtures, 61 assertions
apify run          # local run (uses ./storage)
```

# Actor input Schema

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

Advertisers to pull ads for — one query per entry. Each entry can be a <b>domain</b> (<code>nike.com</code>), a Google <b>advertiser ID</b> (<code>AR01614014350098432001</code> — the <code>AR…</code> segment in any adstransparency.google.com URL, most reliable), a full Transparency Center URL, or a plain <b>company name</b> (<code>Nike</code> — resolved via search suggestions, first match wins).

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

Two-letter country code to filter where ads were shown, e.g. <code>US</code>, <code>GB</code>, <code>IL</code>, <code>DE</code>. Leave as <code>anywhere</code> for global results. Note: Google enforces this filter loosely for some advertisers — treat it as a hint.

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

Maximum number of ads collected per advertiser query.

## `fetchAdDetails` (type: `boolean`):

If enabled (recommended), the Actor calls the per-creative lookup for each ad to extract the creative preview URL, decoded text-ad copy (headline, description, destination URL), first/last shown dates and regions. If disabled, only the lighter search-card data is returned (faster, same price per ad).

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

Proxy to use for the requests. Apify RESIDENTIAL proxy is recommended — it keeps Google consent/captcha interstitials near zero on repeated runs.

## Actor input object example

```json
{
  "queries": [
    "nike.com"
  ],
  "region": "anywhere",
  "maxAdsPerQuery": 100,
  "fetchAdDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("datapeak/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"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("datapeak/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"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call datapeak/google-ads-transparency --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datapeak/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/yHECHdo8zAe77ycMY/builds/qXFRK2BhczXVD5oq4/openapi.json