# Google Ads Transparency Scraper — All Creatives by Advertiser (`scrapeio/google-ads-transparency-ads`) Actor

Extract every ad and creative an advertiser runs in any country from Google Ads Transparency Center. Search by keyword, brand, website, or advertiser ID. Apify AI, MCP, and Cursor ready.

- **URL**: https://apify.com/scrapeio/google-ads-transparency-ads.md
- **Developed by:** [Shop Intel](https://apify.com/scrapeio) (community)
- **Categories:** SEO tools, AI, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## 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 — Extract Every Advertiser's Creatives | Shop Intel on Apify

**Google Ads Transparency Scraper** (Shop Intel / [ScrapeIO on Apify](https://apify.com/scrapeio)) pulls **every public ad and creative** that an advertiser is running on Google's **[Ads Transparency Center](https://adstransparency.google.com/)** — search by **keyword, brand name, website, or advertiser ID**, scope to any **country**, and export a clean Apify **Dataset** (JSON, CSV, Excel, XML, or RSS) for competitive intelligence, creative benchmarking, brand-safety audits, and paid-search research.

> **Companion Actor:** Use the [Google Ads Transparency Advertiser Lookup](https://apify.com/scrapeio/google-ads-transparency-suggest) first to resolve free-text keywords or brands to advertiser IDs, then feed those IDs into this Actor.

### Use with Apify AI

[Apify AI](https://docs.apify.com/account/apify-ai) is live in Apify Console. Describe the job in plain English and it **finds this Actor, fills the input form, runs it, and returns the dataset**. The same ranking powers Store search and the [Apify MCP server](https://docs.apify.com/integrations/mcp) `search-actors` tool used by **Cursor**, Claude, ChatGPT, and other agents.

Use this Actor to pull **every public Google ad creative** an advertiser runs in a country from Ads Transparency Center. Open [Google Ads Transparency Scraper](https://apify.com/scrapeio/google-ads-transparency-ads) or ask Apify AI with the prompts below.

#### Prompts that match this Actor

Type these in the **Apify Store search bar** (long, intent-heavy queries route to Apify AI) or the dashboard **Ask Apify AI** widget:

- "Get all Google ads Nike is running in the United States"
- "Scrape Google Ads Transparency creatives for a brand in India"
- "Extract Google text, image, and video ads for an advertiser ID"
- "Collect competitor Google ads from Ads Transparency Center"
- "Download every creative an advertiser runs in Germany"

#### How Apify AI fills the input

| You say | This Actor sets |
|---|---|
| country code or anywhere | `country` |
| brand, domain, or AR… advertiser ID | `query` |
| known advertiser IDs | `advertiserIds` |
| text / image / video filter | `adFormat` |
| cap per advertiser | `maxAdsPerAdvertiser` |

Apify AI always asks for confirmation before it runs. Nothing is charged until you approve.

#### Cursor, Claude, ChatGPT (Apify MCP)

Pin this Actor as a **default Cursor / MCP tool** so agents call `scrapeio/google-ads-transparency-ads` instead of a random Store result. Keep `actors` + `docs` so Apify AI search still works, and list your suite so Cursor prefers these Actors.

**Cursor MCP URL (this Actor first):**

```text
https://mcp.apify.com?tools=actors,docs,scrapeio/google-ads-transparency-ads,scrapeio/amazon-scraper,scrapeio/google-maps-scraper-advance,scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium,scrapeio/instagram-scraper-premium,scrapeio/whatsapp-scraper-premium,scrapeio/facebook-ad-library-suggestions,scrapeio/google-news-scraper
```

`.cursor/mcp.json` / Cursor Settings → MCP:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=actors,docs,scrapeio/google-ads-transparency-ads,scrapeio/amazon-scraper,scrapeio/google-maps-scraper-advance,scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium,scrapeio/instagram-scraper-premium,scrapeio/whatsapp-scraper-premium,scrapeio/facebook-ad-library-suggestions,scrapeio/google-news-scraper"
    }
  }
}
```

Then: `search-actors` → `fetch-actor-details` → `call-actor` with `scrapeio/google-ads-transparency-ads`. Example:

```text
Use scrapeio/google-ads-transparency-ads to do this: scrape the data I described. Fill the input from my description and return the dataset.
```

### How to scrape Google Ads Transparency Center

Use this **Google Ads Transparency scraper** to download every public creative an advertiser runs in a country. Search by brand, domain, or AR… advertiser ID.

### Google Ads Transparency API for Cursor

Call `scrapeio/google-ads-transparency-ads` from **Cursor** (Apify MCP), Claude, ChatGPT, the [Apify API](https://docs.apify.com/api/v2), Python (`apify-client`), or JavaScript. Apify AI uses the same ranking as Store search: title, description, README, and input/output schemas. This Actor is documented for that ranker — limited permissions, pay-per-event or compute (not rental), and a filled example input.

### What this Actor does

1. Accepts a **`query`** (keyword, brand, domain, or an `AR…` advertiser ID) **or** an explicit list of **`advertiserIds`**.
2. If `query` is a free-text term, it resolves it via Google's internal `SearchSuggestions` RPC and picks the best-matching advertiser (exact match wins, popularity is a tiebreaker).
3. Scopes the search to a **country** (any ISO 3166-1 alpha-2 code, or `anywhere` for no region filter) and optionally filters by **ad format** (text, image, video).
4. Auto-paginates through Google's `SearchCreatives` RPC using a residential **Apify Proxy** session per request, with **exponential-backoff retries** and **session rotation** on every failure.
5. Pushes **one Dataset row per creative** with stable, well-typed fields plus the original `raw` row so you never lose data when Google quietly changes their internal schema.

### Why use this Actor?

| Feature | Detail |
| --- | --- |
| 🌍 **Region-aware** | ISO 3166-1 alpha-2 country codes (`US`, `GB`, `IN`, `DE`, `BR`…), or `anywhere`. |
| 🔎 **Smart query resolution** | Free-text keyword → exact-match advertiser via Google's own SuggestService. |
| 🎯 **Direct advertiser mode** | Pass a list of `AR…` IDs to skip lookup entirely. |
| 🎬 **Format filter** | Limit to `text`, `image`, or `video` creatives. |
| 🛡️ **Residential proxy by default** | Avoids the aggressive datacenter-IP rate limiting on `adstransparency.google.com`. |
| 🔁 **Auto-retry & session rotation** | Up to 5 retries per RPC, fresh proxy session each attempt. |
| 📦 **Stable output schema** | Documented dataset fields + raw row preserved for forward-compatibility. |
| 🧮 **No limits on free** | Pay only for Apify compute units & proxy bandwidth. |

### Input

The full schema lives in [`.actor/input_schema.json`](.actor/input_schema.json). Required fields are marked.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `country` | string | Yes | `US` | ISO 3166-1 alpha-2 code (`US`, `GB`, `IN`, `DE`, `BR`, `FR`, `JP`, `AU`, `CA`…) or `anywhere`. |
| `query` | string | Conditional | — | Keyword, brand, domain, or `AR…` advertiser ID. Required unless `advertiserIds` is set. |
| `advertiserIds` | array\<string> | Conditional | — | One or more `AR…` IDs. Skips the Suggest lookup. Required unless `query` is set. |
| `adFormat` | enum | No | `all` | `all`, `text`, `image`, or `video`. |
| `maxAdsPerAdvertiser` | integer | No | `0` | Hard cap per advertiser. `0` = no limit (paginate until empty). |
| `pageSize` | integer | No | `40` | Creatives per RPC call. Google caps this at ~40. |
| `proxyConfiguration` | object | Yes | RESIDENTIAL | Apify Proxy. Datacenter IPs are heavily rate-limited; **residential strongly recommended**. |

#### Input examples

**Search by brand keyword (resolved automatically):**

```json
{
  "country": "US",
  "query": "nike",
  "adFormat": "all",
  "pageSize": 40,
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}
```

**Pull only video ads for two known advertiser IDs in the UK:**

```json
{
  "country": "GB",
  "advertiserIds": ["AR01234567890123456789", "AR98765432109876543210"],
  "adFormat": "video",
  "maxAdsPerAdvertiser": 500
}
```

**Worldwide pull (no region filter), 100 ads cap:**

```json
{
  "country": "anywhere",
  "query": "adidas",
  "maxAdsPerAdvertiser": 100
}
```

### Output

One dataset record per creative. The complete field list lives in [`.actor/actor.json`](.actor/actor.json) under `storages.dataset.fields`.

| Field | Type | Description |
| --- | --- | --- |
| `advertiserId` | string | Google's `AR…` advertiser ID. |
| `advertiserName` | string | Display name (resolved via Suggest or Lookup). |
| `advertiserCountry` | string | Advertiser's home country (when reported). |
| `region` | string | Country the search was scoped to. |
| `creativeId` | string | Unique creative ID. |
| `creativeUrl` | string | Direct link to the creative on the Transparency Center. |
| `format` | string | `text`, `image`, or `video` (`code:N` if unknown). |
| `imageUrl` | string | Direct image URL (for image creatives). |
| `iframeUrl` | string | Display-ads iframe URL (rich creatives). |
| `imageHtml` | string | Raw image HTML snippet (for image creatives). |
| `firstShown` | string | ISO timestamp of first display. |
| `lastShown` | string | ISO timestamp of most recent display. |
| `impressionsBucket` | object | Google's impression-volume bucket (when present). |
| `raw` | object | Original RPC row, preserved for forward-compatibility. |
| `error` | string | Populated only on per-advertiser failure rows. |

#### Output example

```json
{
  "advertiserId": "AR01234567890123456789",
  "advertiserName": "Nike, Inc.",
  "advertiserCountry": "US",
  "region": "US",
  "creativeId": "CR98765432109876543210",
  "creativeUrl": "https://adstransparency.google.com/advertiser/AR01234567890123456789/creative/CR98765432109876543210?region=US",
  "format": "video",
  "imageUrl": null,
  "iframeUrl": "https://displayads-formats.googleusercontent.com/.../ad.html",
  "imageHtml": null,
  "firstShown": "2025-09-01T00:00:00.000Z",
  "lastShown": "2026-05-10T00:00:00.000Z",
  "impressionsBucket": { "1": "10K_TO_100K" },
  "raw": { "1": "AR01234567890123456789", "2": "CR98765432109876543210", "...": "..." }
}
```

Datasets export as JSON, CSV, XLSX, XML, RSS, or as Apify API JSON straight to your data warehouse.

### Use cases

- **Competitive intelligence** — monitor every ad a competitor is running across regions.
- **Creative benchmarking** — pull video creatives at scale to feed analysis or ML pipelines.
- **Brand safety audits** — verify what an agency is actually running on your behalf.
- **Paid-search research** — combine with the [Google Ads Transparency Advertiser Lookup](https://apify.com/scrapeio/google-ads-transparency-suggest) to map a keyword universe to all matching advertisers.
- **Litigation & compliance** — capture timestamped public evidence of an advertiser's creative across jurisdictions.
- **Trend tracking** — track new ad formats or messaging shifts week over week.

### How to run on Apify

1. Open [Google Ads Transparency Scraper on Apify](https://apify.com/scrapeio/google-ads-transparency-ads) and click **Try for free**.
2. Pick a `country`, type a `query` (e.g. `nike`) **or** paste `advertiserIds`.
3. Optionally pick `adFormat` and `maxAdsPerAdvertiser`.
4. Click **Start** and watch results stream into **Storage → Dataset**.
5. Export as JSON / CSV / Excel from the Dataset page, or hit the API.

#### CLI example

```bash
apify call scrapeio/google-ads-transparency-ads --input='{
  "country": "US",
  "query": "nike",
  "adFormat": "video",
  "maxAdsPerAdvertiser": 200
}'
```

#### Apify API example

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/scrapeio~google-ads-transparency-ads/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"country":"GB","query":"adidas","adFormat":"all","maxAdsPerAdvertiser":100}'
```

### Run locally

```bash
cd google-ads-actor
npm install
mkdir -p storage/key_value_stores/default
echo '{"country":"US","query":"nike","maxAdsPerAdvertiser":50,"proxyConfiguration":{"useApifyProxy":true,"apifyProxyGroups":["RESIDENTIAL"]}}' \
  > storage/key_value_stores/default/INPUT.json
apify run
```

You need an Apify token with **Residential Proxy** access for non-trivial runs.

### How it works (technical notes)

- **No public API** — Google does not document or expose the Ads Transparency Center programmatically. This Actor calls the same internal `SearchService/SearchSuggestions`, `SearchService/SearchCreatives`, and `LookupService/GetAdvertiserById` JSON-RPC endpoints that the live web UI calls. Field positions are reverse-engineered from captured live sessions; the original RPC row is preserved in `raw` so consumers can recover fields when Google shifts the schema.
- **Pagination** — Google returns a continuation token (`data["2"]`) in the response; the Actor walks tokens until the response is empty or `maxAdsPerAdvertiser` is hit.
- **Rate limiting** — datacenter IPs get a `429` within a handful of requests. With **RESIDENTIAL** proxy + per-request session rotation + exponential-backoff retries the actor survives long runs.
- **Region scoping** — country names map to numeric `geoTargetId` codes (e.g. `US` → `2840`). `anywhere` omits the region filter entirely.

### FAQ

**How do I download Google ads for a competitor?**
Set country and query (or advertiserIds). Pin scrapeio/google-ads-transparency-ads in Cursor MCP.

**Can I run this Actor with Apify AI?**
Yes. In [Apify Console](https://console.apify.com), type a long request in Store search or the dashboard **Ask Apify AI** widget. Apify AI matches this README, fills the input schema, asks you to confirm, then returns the dataset. This Actor uses **limited permissions** (not full-account access) and is not a rental Actor, so it is eligible for Apify AI.

**Does this work from Cursor, Claude, or ChatGPT?**
Yes. Connect the [Apify MCP server](https://mcp.apify.com). Agents call `search-actors`, `fetch-actor-details`, and `call-actor`. Ranking uses the same signals as Store search and Actor quality score: a clear README plus documented input and output schemas.

**Is scraping Google Ads Transparency legal?**
The Transparency Center is a public Google product and the data is published by advertisers for public viewing. This Actor only retrieves public data through the same endpoints your browser uses. You are responsible for complying with Google's [Terms of Service](https://policies.google.com/terms), your local laws, and any contracts you have with downstream users.

**Why is the proxy required?**
Without residential IPs you'll hit `429 Too Many Requests` within seconds. The free Apify proxy tier works for small runs; for production traffic you'll want a paid plan with residential bandwidth.

**How do I find an advertiser ID?**
Use the companion [Google Ads Transparency Advertiser Lookup](https://apify.com/scrapeio/google-ads-transparency-suggest) Actor — it turns any keyword, brand, or domain into a list of verified `AR…` IDs.

**Why doesn't every creative have an `imageUrl`?**
Google serves text, static-image, and rich (HTML/video) creatives through different fields. The Actor maps the most common shapes into `imageUrl` / `iframeUrl` / `imageHtml`; if a creative uses a shape not yet mapped, the data is preserved in `raw` and you can extract it downstream.

**Can I paginate forever?**
Set `maxAdsPerAdvertiser` to `0`. Pagination stops automatically when Google returns no continuation token.

**How much does it cost?**
You only pay for **Apify compute units** and **Residential Proxy bandwidth**. A typical advertiser with ~500 creatives runs in <2 minutes of CU and ~50 MB of proxy traffic.

### Shop Intel / ScrapeIO actor suite

Pair this Actor with the rest of the **Shop Intel** ad-intelligence suite for a complete cross-platform paid-media monitoring stack:

- **[Google Ads Transparency Advertiser Lookup](https://apify.com/scrapeio/google-ads-transparency-suggest)** — resolve keywords/brands/domains to advertiser IDs.
- **[LinkedIn Ad Library Scraper](https://apify.com/scrapeio/linkedin-ad-library-scraper)** — B2B ads at scale.
- **[Facebook Ad Library Scraper](https://apify.com/scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium)** — Meta transparency ads.
- **[Instagram Ads Scraper](https://apify.com/scrapeio/instagram-scraper-premium)** — Instagram-only ad library.
- **[YouTube Ad Scraper](https://apify.com/scrapeio/youtube-ad-scraper)** — brand- or keyword-scoped YouTube ads.
- **[YouTube Brand Finder](https://apify.com/scrapeio/youtube-brand-finder)** — resolve brand names to YouTube `brandId` values.
- **[YouTube Video Downloader](https://apify.com/scrapeio/youtube-downloader)** — archive specific videos or shorts.
- **[Google News Scraper](https://apify.com/scrapeio/google-news-scraper)** — headline and source monitoring.
- **[Google Maps Scraper](https://apify.com/scrapeio/google-maps-scraper-advance)** — local business leads.
- **[Amazon Scraper](https://apify.com/scrapeio/amazon-scraper)** — search rankings and product data.

### Compliance & terms

Use public transparency data responsibly. You are responsible for complying with Google's [Terms of Service](https://policies.google.com/terms), the [Ads Transparency Center](https://adstransparency.google.com/) usage guidelines, applicable copyright law, and your own data policies.

***

Built by **[ScrapeIO](https://apify.com/scrapeio)** on Apify.

Powered by **[AdScrape](https://www.adscrape.in/)**.

**Support:** open an issue on the Actor's Apify page or message us on the [Apify Discord](https://discord.com/invite/jyEM2PRvMU).

# Actor input Schema

## `country` (type: `string`):

ISO 3166-1 alpha-2 country code for the region to search ads in (e.g. US, GB, IN, DE). Use 'anywhere' for no region filter.

## `query` (type: `string`):

What to search. Can be a keyword/brand name (e.g. 'nike'), a website (e.g. 'nike.com'), or an exact advertiser ID starting with 'AR' (e.g. 'AR01234567890123456789'). If a keyword or website is given, the actor first resolves it to the best-matching advertiser via the Suggest RPC.

## `advertiserIds` (type: `array`):

Optional list of advertiser IDs to scrape directly, skipping the query lookup. Use this when you already have IDs from the suggest actor.

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

Filter creatives by format.

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

Stop after collecting this many creatives per advertiser (0 = no limit).

## `pageSize` (type: `integer`):

Creatives requested per RPC call (Google caps this around 40).

## Actor input object example

```json
{
  "country": "US",
  "query": "nike",
  "adFormat": "all",
  "maxAdsPerAdvertiser": 0,
  "pageSize": 40
}
```

# Actor output Schema

## `creatives` (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 = {
    "query": "nike"
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapeio/google-ads-transparency-ads").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 = { "query": "nike" }

# Run the Actor and wait for it to finish
run = client.actor("scrapeio/google-ads-transparency-ads").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 '{
  "query": "nike"
}' |
apify call scrapeio/google-ads-transparency-ads --silent --output-dataset

```

## MCP server setup

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

```

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/Gxc3FH43KASFJRmpR/builds/4TOJJAYO9Zd7ghupu/openapi.json