# Google Ads Archive (`danthedataman/google-ads-archive`) Actor
Export every ad an advertiser runs on Google, from the official Ads Transparency Center: creative image, first and last shown dates, format, and a link to the ad on Google. Any country, no API key.
- **URL**: https://apify.com/danthedataman/google-ads-archive.md
- **Developed by:** [Eli J](https://apify.com/danthedataman) (community)
- **Categories:** Marketing, Business, SEO tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
from $0.26 / 1,000 results
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/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.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 Archive
Export an advertiser's ads from Google's own **Ads Transparency Center** — text,
image and video creatives — as clean JSON, CSV or Excel. No API key, no browser,
no scraping code.
Google publishes this archive but gives it no API and no export button. This
Actor turns it into a table.
### What you get
One row per ad creative: Google's own format for it, the image and its pixel
size where the creative has one, the dates it first and last ran, and a link
back to the ad on Google so anything can be checked at source.
By default a run collects up to 100 ads per advertiser — large brands run
thousands, so raise `maxAdsPerAdvertiser` (or set it to `0`) when you want the
full history, and watch the cost.
### How to scrape Google ads by advertiser
Put one or more advertiser names in **Advertisers** and run it. A name is
resolved against Google's own advertiser directory and the closest match is
used; when a brand has several registered entities the alternatives are listed
in the log so you can switch to an exact id.
```json
{
"advertisers": ["Nike, Inc."],
"region": "US",
"maxAdsPerAdvertiser": 100
}
````
To pin an exact advertiser, pass its Google id instead:
```json
{
"advertisers": ["AR16735076323512287233"],
"region": "GB"
}
```
### Competitor ad research and creative tracking
Because every row carries `firstShown` and `lastShown`, a single run tells you
which creatives a competitor is still running, which they retired, and how long
each has been live. Re-run it on a schedule and the diff is a creative-rotation
timeline.
Ads differ by country: an advertiser with thousands of ads in the US may have
none in Germany. Set **Region** per market.
### Input
| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `advertisers` | array | — | Advertiser names (`Nike, Inc.`) or Google advertiser ids (`AR16735076323512287233`). Required — with none set the run stops and charges nothing. |
| `region` | string | `US` | `US`, `GB`, `DE`, `IN`, `CA`, `AU` or `JP`. For any other country pass Google's numeric region code (2000 + the ISO-3166-1 numeric country code). |
| `maxAdsPerAdvertiser` | integer | `100` | Stop after this many ads per advertiser. A large advertiser can run thousands — Google reports 9,000-10,000 for Nike in the US alone — so this is the main cost control. `0` means no limit. |
| `maxItems` | integer | `0` | Stop the whole run after this many rows. `0` means no limit. |
| `maxRunSeconds` | integer | `900` | Stop starting new pages after this many seconds. `0` disables the budget. |
| `maxRetriesPerRequest` | integer | `8` | Retries when Google rate-limits a request; each one backs off and rotates the proxy IP. |
| `rotateAfterRequests` | integer | `24` | Retire a proxy identity after this many requests, before Google throttles it. `0` disables proactive rotation. |
| `proxyConfiguration` | object | Apify Proxy | Google rate-limits a single address with `429` during sustained reading, so leaving the proxy on is strongly recommended. |
### Output
```json
{
"advertiserId": "AR16735076323512287233",
"advertiserName": "Nike, Inc.",
"creativeId": "CR05576182909712203777",
"format": "text",
"formatCode": 1,
"imageUrl": "https://tpc.googlesyndication.com/archive/simgad/10891172661046192318",
"imageWidth": 348,
"imageHeight": 174,
"previewUrl": null,
"firstShown": "2022-11-30",
"lastShown": "2026-07-27",
"firstShownTimestamp": 1669820166,
"lastShownTimestamp": 1785116984,
"region": "US",
"regionCode": 2840,
"creativeUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR05576182909712203777?region=US",
"scrapedAt": "2026-07-27T01:10:00+00:00"
}
```
That row is a real one, taken verbatim from a live run. Note it: a **text** ad
that carries an image. That is normal, and it is why you should filter on
`format` rather than on whether `imageUrl` is set.
**`format`** is Google's own classification, read from the format code it
returns, not inferred from what the creative happens to contain:
| `formatCode` | `format` |
| --- | --- |
| `1` | `text` |
| `2` | `image` |
| `3` | `video` |
Anything else is reported as `other` with the raw `formatCode` kept, so a new
Google format arrives visible rather than silently mislabelled. Do not infer the
format from whether a row has an image: **text ads carry images too**, so
filtering on `imageUrl` returns search ads alongside display ones.
**Dates.** `firstShown` and `lastShown` are the UTC date of the instants Google
returns. Those instants are not midnight boundaries, so a reader in another
timezone may want a different calendar date — `firstShownTimestamp` and
`lastShownTimestamp` carry the raw epoch seconds for exactly that.
**`previewUrl`** is Google's own preview endpoint for the creative. It is a
script payload meant to be embedded by Google's viewer rather than a standalone
page, so treat it as an identifier for the creative rather than a link to hand
to a browser. `imageUrl` and `creativeUrl` are ordinary URLs.
### Cost
Billing is pay per result: one event per ad row, and nothing else. A failed
request is never written to the dataset, so you are not charged for this Actor's
errors. Passing the same advertiser twice — by name and by id, say — collects it
once, so a duplicated list does not become a duplicated invoice.
A run whose advertisers exist but have no ads in that region finishes
successfully with an empty dataset and an explanation in the log. So does a run
where a name matches nothing: that is an answer, not a failure. A run fails only
when every advertiser was actually unreadable, with the reason in the status
message.
Set `maxAdsPerAdvertiser` to bound a run before you start it — that is the field
that decides what a large advertiser costs.
### Notes and limits
- Only advertisers Google has verified appear in the Transparency Center, and
only ads Google still retains are listed. This Actor reports what that archive
contains; it cannot show ads Google has removed.
- An advertiser must be specified. Google's archive has no "all advertisers"
view, so there is no way to sweep a whole category in one call.
- Ad counts, spend and impression ranges shown for political ads in some
regions are not included — this Actor returns creatives.
# Actor input Schema
## `advertisers` (type: `array`):
Advertiser names as Google lists them (e.g. Nike, Inc.) or Google advertiser ids (e.g. AR16735076323512287233). A name is resolved to the closest match and the alternatives are printed in the log, so pass an id when a brand has several registered entities.
## `region` (type: `string`):
Which country's ad archive to read. Two-letter code US, GB, DE, IN, CA, AU or JP. For any other country pass Google's numeric region code (2000 + the ISO-3166-1 numeric country code). An advertiser's ads differ by region.
## `maxAdsPerAdvertiser` (type: `integer`):
Stop after this many ads for each advertiser. A large advertiser can run thousands (Google reports 9,000-10,000 for Nike in the US alone), so this is the main cost control. 0 means no per-advertiser limit.
## `maxItems` (type: `integer`):
Stop the whole run after this many rows. 0 means no overall limit.
## `maxRunSeconds` (type: `integer`):
Stop starting new pages after this many seconds, so a Google-side slowdown cannot burn a long run. 0 disables the budget.
## `maxRetriesPerRequest` (type: `integer`):
How hard to retry when Google rate-limits a request. Each retry backs off and rotates onto a fresh proxy IP.
## `rotateAfterRequests` (type: `integer`):
Retire each proxy identity after this many requests, before Google throttles it. 0 disables proactive rotation.
## `proxyConfiguration` (type: `object`):
The Transparency Center rate-limits a single address with HTTP 429 during sustained reading. Keeping Apify Proxy enabled is strongly recommended.
## Actor input object example
```json
{
"advertisers": [
"AR16735076323512287233"
],
"region": "GB",
"maxAdsPerAdvertiser": 100,
"maxItems": 0,
"maxRunSeconds": 900,
"maxRetriesPerRequest": 8,
"rotateAfterRequests": 24,
"proxyConfiguration": {
"useApifyProxy": true
}
}
```
# 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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"advertisers": [
"Nike, Inc."
]
};
// Run the Actor and wait for it to finish
const run = await client.actor("danthedataman/google-ads-archive").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 '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = { "advertisers": ["Nike, Inc."] }
# Run the Actor and wait for it to finish
run = client.actor("danthedataman/google-ads-archive").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 '{
"advertisers": [
"Nike, Inc."
]
}' |
apify call danthedataman/google-ads-archive --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=danthedataman/google-ads-archive",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Google Ads Archive",
"description": "Export every ad an advertiser runs on Google, from the official Ads Transparency Center: creative image, first and last shown dates, format, and a link to the ad on Google. Any country, no API key.",
"version": "0.1",
"x-build-id": "TA8kamnEzARqWKh7n"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/danthedataman~google-ads-archive/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-danthedataman-google-ads-archive",
"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/danthedataman~google-ads-archive/runs": {
"post": {
"operationId": "runs-sync-danthedataman-google-ads-archive",
"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/danthedataman~google-ads-archive/run-sync": {
"post": {
"operationId": "run-sync-danthedataman-google-ads-archive",
"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": {
"advertisers": {
"title": "Advertisers",
"type": "array",
"description": "Advertiser names as Google lists them (e.g. Nike, Inc.) or Google advertiser ids (e.g. AR16735076323512287233). A name is resolved to the closest match and the alternatives are printed in the log, so pass an id when a brand has several registered entities.",
"items": {
"type": "string"
}
},
"region": {
"title": "Region",
"type": "string",
"description": "Which country's ad archive to read. Two-letter code US, GB, DE, IN, CA, AU or JP. For any other country pass Google's numeric region code (2000 + the ISO-3166-1 numeric country code). An advertiser's ads differ by region.",
"default": "US"
},
"maxAdsPerAdvertiser": {
"title": "Max ads per advertiser",
"minimum": 0,
"type": "integer",
"description": "Stop after this many ads for each advertiser. A large advertiser can run thousands (Google reports 9,000-10,000 for Nike in the US alone), so this is the main cost control. 0 means no per-advertiser limit.",
"default": 100
},
"maxItems": {
"title": "Max results in total",
"minimum": 0,
"type": "integer",
"description": "Stop the whole run after this many rows. 0 means no overall limit.",
"default": 0
},
"maxRunSeconds": {
"title": "Run time budget (seconds)",
"minimum": 0,
"type": "integer",
"description": "Stop starting new pages after this many seconds, so a Google-side slowdown cannot burn a long run. 0 disables the budget.",
"default": 900
},
"maxRetriesPerRequest": {
"title": "Max retries per request",
"minimum": 1,
"maximum": 20,
"type": "integer",
"description": "How hard to retry when Google rate-limits a request. Each retry backs off and rotates onto a fresh proxy IP.",
"default": 8
},
"rotateAfterRequests": {
"title": "Rotate proxy IP every N requests",
"minimum": 0,
"maximum": 200,
"type": "integer",
"description": "Retire each proxy identity after this many requests, before Google throttles it. 0 disables proactive rotation.",
"default": 24
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "The Transparency Center rate-limits a single address with HTTP 429 during sustained reading. Keeping Apify Proxy enabled is strongly recommended.",
"default": {
"useApifyProxy": true
}
}
}
},
"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
}
}
}
}
}
}
}
}
}
}
```