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

Unlock competitor insights! Extract ads by name, URL, or ID. Get precise data: impressions by region/platform (YT, Search, Display), targeting flags, and dates. Use Rich Variations mode for CTAs, URLs, and images. Fast, structured JSON output. 🎯⚖️

- **URL**: https://apify.com/donjuan\_mime/google-ads.md
- **Developed by:** [Donjuan](https://apify.com/donjuan_mime) (community)
- **Categories:** SEO tools, Developer tools, Social media
- **Stats:** 7 total users, 3 monthly users, 88.2% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 results

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

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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
A script for scraping creatives from the Google Ads Transparency Center (`adstransparency.google.com`).

### Overview
This script is designed for the Apify platform. It resolves a target advertiser (by name, URL, or ID), enumerates the advertiser's creatives using a headless Chromium browser via Playwright, and fetches the full detail of each creative through the public `LookupService/GetCreativeById` RPC. Results are written to the dataset as structured JSON.

### Features
- Accepts an advertiser **name**, a full Transparency Center **URL**, or a raw **advertiser ID** (`AR...`).
- Automatically parses `region` and `preset-date` out of a provided URL.
- Returns every creative's first/last-shown dates, served days, format, targeting flags, per-region impressions, and per-surface (Search / YouTube / Display / …) impression breakdowns.
- Resolves Google's numeric geo-target IDs to ISO 3166-1 alpha-2 codes and country names.
- Optional `rich_variations` mode renders each creative in a headless browser to additionally extract `clickUrl`, `cta`, `description`, and `imageUrl` per variation (significantly slower).

### Input
#### Parameters
- **advertiser_name**: Organisation name to search (e.g. `"Niantic, Inc."`). Used only if `advertiser_url` and `advertiser_id` are empty; multiple matches are all scraped.
- **advertiser_url**: Full Ads Transparency Center URL. `region` and `preset-date` from the URL are applied automatically.
- **advertiser_id**: Known advertiser ID starting with `AR`.
- **region**: Region filter — `anywhere` (default) or an ISO alpha-2 code such as `DE`, `ES`, `US`. Overridden by the URL's `region` param if present.
- **preset_date**: Optional preset date-range filter matching the UI (e.g. `"Last 30 days"`).
- **limit**: Max creatives to fetch per advertiser. Default `100`.
- **rich_variations**: When `true`, each creative is rendered in a headless browser to fill variation-level `clickUrl`, `cta`, `description`, and `imageUrl`. Adds roughly **12 seconds per creative** — disabled by default.

#### Format
```json
{
  "advertiser_url": "https://adstransparency.google.com/advertiser/AR08888592736429539329?authuser=0&region=ES&preset-date=Last+30+days",
  "limit": 10,
  "rich_variations": false
}
````

Or, by organisation name:

```json
{
  "advertiser_name": "Niantic, Inc.",
  "region": "anywhere",
  "limit": 100
}
```

### Output

The script outputs a JSON array where each object represents one creative with its region stats, targeting flags, and variations.

#### Example Output

```json
[
  {
    "adLibraryUrl": "https://adstransparency.google.com/advertiser/AR08888592736429539329/creative/CR08436770543486631937",
    "advertiserId": "AR08888592736429539329",
    "advertiserName": "Niantic, Inc.",
    "creativeId": "CR08436770543486631937",
    "firstShown": "2023-07-04",
    "format": "IMAGE",
    "lastShown": "2024-05-17",
    "numServedDays": 319,
    "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js?...",
    "regionStats": [
      {
        "regionCode": "DE",
        "regionName": "Germany",
        "firstShown": "2023-07-04",
        "lastShown": "2024-05-17",
        "impressions": { "lowerBound": 1000, "upperBound": 2000 },
        "surfaceServingStats": [
          { "surfaceCode": "YOUTUBE", "surfaceName": "YouTube",
            "impressions": { "lowerBound": 1000, "upperBound": 2000 } },
          { "surfaceCode": "SEARCH", "surfaceName": "Google Search",
            "impressions": { "lowerBound": 0, "upperBound": 1000 } }
        ]
      }
    ],
    "startUrl": "https://adstransparency.google.com/advertiser/AR08888592736429539329?region=anywhere",
    "targeting": {
      "targetingCategory": {
        "demographics":    { "1": true,  "2": false },
        "geography":       { "1": true,  "2": true  },
        "contextual":      { "1": true,  "2": true  },
        "advertiserList":  { "1": false, "2": true  }
      }
    },
    "variations": [
      {
        "clickUrl": "https://play.google.com/store/apps/details?id=com.nianticlabs.pokemongo",
        "cta": "Install",
        "description": "Catch Pokémon, battle other Trainers, raid with friends, and more in Pokémon GO",
        "imageUrl": "https://tpc.googlesyndication.com/simgad/16977068568541754968",
        "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js?..."
      }
    ]
  }
]
```

When `rich_variations` is `false` (default), each `variations[]` entry contains only `previewUrl`; `clickUrl`, `cta`, `description`, and `imageUrl` are only populated when `rich_variations` is `true`.

### How to Use

1. Set up a new task on the Apify platform.
2. Configure the input JSON with **one** of `advertiser_url`, `advertiser_id`, or `advertiser_name`, plus any optional filters.
3. Run the task. The script writes each creative as a separate record to the dataset.

### Notes & Limitations

- Advertisers with many thousands of creatives will take proportionally longer; use `limit` to cap per-advertiser work.
- `rich_variations` multiplies run time by roughly `limit × 12 seconds`. Use only when you need variation-level `clickUrl`/`cta`/`description`/`imageUrl`.
- `imageUrl` is best-effort — small AppInstall ad units that render images through canvas/CSS may leave it empty.
- Unknown region IDs fall back to the raw numeric Google geo-target ID.

### Disclaimer

This script is provided "as is" without any warranties. Users assume full responsibility for its use. Ensure compliance with Google's terms of service and applicable legal regulations when using this scraper.

# Actor input Schema

## `advertiser_name` (type: `string`):

Organisation name to search for (e.g. 'Niantic, Inc.'). Leave empty if advertiser\_url or advertiser\_id is provided.

## `advertiser_url` (type: `string`):

Full Ads Transparency Center advertiser URL (e.g. https://adstransparency.google.com/advertiser/AR08888592736429539329?region=ES). Region and preset-date from the URL are applied automatically.

## `advertiser_id` (type: `string`):

Advertiser ID (AR...) if already known.

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

Region filter — use 'anywhere' for all, or an ISO-3166-1 alpha-2 code such as 'DE', 'ES', 'US'.

## `preset_date` (type: `string`):

Optional preset-date filter (values the UI uses, e.g. 'Last 30 days').

## `limit` (type: `integer`):

How many creatives to fetch per advertiser. Default 100.

## `rich_variations` (type: `boolean`):

When enabled, a render is launched in a headless browser for each creative to extract the clickUrl, cta, description, and imageUrl for each variant. This provides significantly more information, but is much slower: it adds ~12 seconds per creative.

## Actor input object example

```json
{
  "advertiser_url": "https://adstransparency.google.com/advertiser/AR08888592736429539329?region=ES&preset-date=Last+30+days",
  "region": "anywhere",
  "limit": 100,
  "rich_variations": false
}
```

# Actor output Schema

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

Tabular view of scraped ads — uses the 'overview' view defined on the default dataset.

## `adsJson` (type: `string`):

Full JSON payload for every scraped creative: variations, regionStats, surfaceServingStats, targeting.

## `adsCsv` (type: `string`):

CSV export of the 'overview' fields — handy for spreadsheet analysis.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("donjuan_mime/google-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 = {}

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

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

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

```

## CLI example

```bash
echo '{}' |
apify call donjuan_mime/google-ads --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=donjuan_mime/google-ads",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Google Ads Transparency Center Scraper",
        "description": "Unlock competitor insights! Extract ads by name, URL, or ID. Get precise data: impressions by region/platform (YT, Search, Display), targeting flags, and dates. Use Rich Variations mode for CTAs, URLs, and images. Fast, structured JSON output. 🎯⚖️",
        "version": "0.0",
        "x-build-id": "UkyCjIgBja3Fbvqvg"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/donjuan_mime~google-ads/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-donjuan_mime-google-ads",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/donjuan_mime~google-ads/runs": {
            "post": {
                "operationId": "runs-sync-donjuan_mime-google-ads",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/donjuan_mime~google-ads/run-sync": {
            "post": {
                "operationId": "run-sync-donjuan_mime-google-ads",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "advertiser_name": {
                        "title": "Advertiser name",
                        "type": "string",
                        "description": "Organisation name to search for (e.g. 'Niantic, Inc.'). Leave empty if advertiser_url or advertiser_id is provided."
                    },
                    "advertiser_url": {
                        "title": "Advertiser URL",
                        "type": "string",
                        "description": "Full Ads Transparency Center advertiser URL (e.g. https://adstransparency.google.com/advertiser/AR08888592736429539329?region=ES). Region and preset-date from the URL are applied automatically.",
                        "default": "https://adstransparency.google.com/advertiser/AR08888592736429539329?region=ES&preset-date=Last+30+days"
                    },
                    "advertiser_id": {
                        "title": "Advertiser ID",
                        "type": "string",
                        "description": "Advertiser ID (AR...) if already known."
                    },
                    "region": {
                        "title": "Region",
                        "type": "string",
                        "description": "Region filter — use 'anywhere' for all, or an ISO-3166-1 alpha-2 code such as 'DE', 'ES', 'US'.",
                        "default": "anywhere"
                    },
                    "preset_date": {
                        "title": "Preset date range",
                        "type": "string",
                        "description": "Optional preset-date filter (values the UI uses, e.g. 'Last 30 days')."
                    },
                    "limit": {
                        "title": "Max ads per advertiser",
                        "minimum": 1,
                        "type": "integer",
                        "description": "How many creatives to fetch per advertiser. Default 100.",
                        "default": 100
                    },
                    "rich_variations": {
                        "title": "Extract full variation details (slower)",
                        "type": "boolean",
                        "description": "When enabled, a render is launched in a headless browser for each creative to extract the clickUrl, cta, description, and imageUrl for each variant. This provides significantly more information, but is much slower: it adds ~12 seconds per creative.",
                        "default": false
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```