# Google Ads Transparency Scraper (`straightforward_hydra/google-ads-transparency-scraper`) Actor

Pull every ad an advertiser runs on Google Search, YouTube and Display from Google's Ads Transparency Center: creative image or preview, format, first and last shown dates, and an optional per-country breakdown. Keyless, no browser.

- **URL**: https://apify.com/straightforward\_hydra/google-ads-transparency-scraper.md
- **Developed by:** [Dev D](https://apify.com/straightforward_hydra) (community)
- **Categories:** E-commerce, Automation, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Google Ads Transparency Scraper

Pull every ad an advertiser runs on **Google Search, YouTube, Display and Shopping** straight from Google's [Ads Transparency Center](https://adstransparency.google.com) — the creative itself, its format, and the dates it ran.

Point it at a brand name, a domain, or an advertiser ID and get one clean row per ad.

**No API key. No browser. No login.**

### What you get

| Field | Description |
|---|---|
| `advertiser_name` / `advertiser_id` | The verified advertiser who paid for the ad |
| `creative_id` | Google's ID for this specific ad |
| `format` | `image`, `video` or `text` |
| `image_url` / `creative_url` | The creative asset, or its rendered preview |
| `first_shown` / `last_shown` | When the ad started and last ran |
| `advertiser_total_ads` | How many ads this advertiser is running in total |
| `ad_url` / `advertiser_url` | Links back to the Transparency Center |
| `regions_shown` *(optional)* | Every country the ad ran in, with per-country last-shown dates |
| `variants` *(optional)* | Each creative variation in the ad |

### Who uses this

- **Competitive intelligence** — see every creative a competitor is running, and when they started
- **Agencies & DTC brands** — pull rivals' live ad copy and imagery before a campaign
- **Ad-creative research** — build swipe files of what's actually running in your category
- **Market monitoring** — track when a competitor enters or exits a country
- **Fraud & brand safety** — find who is advertising against your brand name

### Input

```json
{
  "queries": ["nike.com", "Adidas", "AR07896982249181020161"],
  "mode": "ads",
  "region": "US",
  "maxAdsPerAdvertiser": 50,
  "includeDetails": false
}
```

| Option | Default | Notes |
|---|---|---|
| `queries` | `["Adidas"]` | Advertiser names, domains, or raw advertiser IDs — mix freely |
| `mode` | `ads` | `ads` = one row per creative. `advertisers` = discover who advertises under a name |
| `region` | `anywhere` | Two-letter country code (`US`, `GB`, `DE`, `IN`…). 237 regions supported |
| `maxAdsPerAdvertiser` | `50` | Pages through 40 at a time up to this limit |
| `maxAdvertisersPerQuery` | `1` | Only applies to name searches |
| `includeDetails` | `false` | Adds per-country breakdown and creative variants (one extra request per ad) |

#### Getting the right advertiser

**Use a domain when you can.** `nike.com` resolves exactly to *Nike Retail BV*, while the name `Nike` returns whatever Google's index ranks highest — often smaller accounts with similar spellings.

Not sure who you want? Run `mode: "advertisers"` first to list the candidates with their ad counts, then feed the right `advertiser_id` back in.

### Output

```json
{
  "advertiser_id": "AR07896982249181020161",
  "advertiser_name": "ADIDAS",
  "creative_id": "CR14548376359924662273",
  "format": "image",
  "image_url": "https://tpc.googlesyndication.com/archive/simgad/7087140508781166450",
  "first_shown": "2024-03-31",
  "last_shown": "2026-08-11",
  "advertiser_total_ads": 862,
  "ad_url": "https://adstransparency.google.com/advertiser/AR07896982249181020161/creative/CR14548376359924662273"
}
```

### Notes

- **An advertiser may run no ads in a given country.** If a region filter returns nothing, that is usually a real answer, not an error — widen `region` to `anywhere` to confirm.
- **Large advertisers run thousands of ads.** Raise `maxAdsPerAdvertiser` *and* the run timeout together. If the run would exceed its timeout, the Actor stops cleanly and keeps everything collected so far rather than failing.
- **Heavy runs may be rate-limited** by Google from a single IP. Enable the proxy option for large jobs.
- Ad transparency data is published by Google under the EU **Digital Services Act**. It is public, non-personal disclosure data about advertising.

### Pricing

Pay per event:

- `ad` — one ad creative
- `ad-details` — an ad enriched with its per-country breakdown and variants (costs an extra upstream request)
- `advertiser` — one advertiser row in `advertisers` mode

# Actor input Schema

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

Advertiser names ("Nike"), domains ("nike.com") or raw advertiser IDs ("AR01614014350098432001"). Domains and IDs resolve exactly; names are matched against Google's advertiser index.

## `mode` (type: `string`):

ads = one row per ad creative. advertisers = one row per advertiser (use this first to find the exact advertiser behind a brand name, then feed its ID back in).

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

Two-letter country code to restrict ads to one market, e.g. US, GB, DE, IN, AU. Leave as "anywhere" for every market. 237 regions supported. Note: an advertiser may run no ads at all in a given country.

## `maxAdsPerAdvertiser` (type: `integer`):

Upper bound on creatives pulled for each advertiser. Large advertisers run thousands; the Actor pages through 40 at a time until it hits this number.

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

How many matching advertisers to take for each name you search. 1 keeps only the best match, which is usually what you want. Ignored for domains and advertiser IDs.

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

Adds every creative variant and the list of countries the ad ran in, with per-country last-shown dates. Costs one extra request per ad, so it is slower and billed as a separate, higher-priced event.

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

Optional. The Ads Transparency Center is reachable without a proxy, but Google rate-limits heavy use from one IP — enable this for large runs.

## Actor input object example

```json
{
  "queries": [
    "Adidas",
    "nike.com"
  ],
  "mode": "ads",
  "region": "anywhere",
  "maxAdsPerAdvertiser": 50,
  "maxAdvertisersPerQuery": 1,
  "includeDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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": [
        "Adidas",
        "nike.com"
    ],
    "region": "anywhere"
};

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

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

```

## MCP server setup

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

```

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/O70ecxZLycUEqS7TI/builds/fxrmC1mGDxb1cW0dn/openapi.json