# Google Ads Advertiser Creative History Scraper (`nimbryxo-studio/google-ads-advertiser-creative-history-scraper`) Actor

Look up an advertiser's ad history on the Google Ads Transparency Center by URL, name, or domain, with ad format, preview media, and first/last shown dates per creative.

- **URL**: https://apify.com/nimbryxo-studio/google-ads-advertiser-creative-history-scraper.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** Automation, Lead generation, SEO tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 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.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Advertiser Creative History Scraper

Look up any advertiser's ad history on Google's Ads Transparency Center, either by pasting the advertiser's own Transparency Center URL or by searching for them by name or domain. Get back the advertiser's creatives Google has on record, up to the limit you set, with format, preview media, and the dates each ad ran.

### What this actor does

- Scrapes a specific advertiser's creatives from a direct Ads Transparency Center URL, up to `resultsLimit` per advertiser
- Finds one matching advertiser per name or domain and scrapes their creatives without needing the URL
- Covers all three ad formats Google's Transparency Center exposes: text, image, and video
- Can skip the per-ad detail fetch for a faster run that relies on the summary Google shows in the advertiser's ad list
- Filters results to ads shown in a specific country
- Fields that don't apply to a given ad (for example `videoUrl` on a text ad) come back as `null` rather than a placeholder

### Output per ad

- `advertiserId`, `advertiserName` — the advertiser the ad belongs to and Google's ID for them
- `creativeId` — Google's unique ID for this specific ad creative
- `format` — `TEXT`, `IMAGE`, or `VIDEO`; `UNKNOWN` if Google returns a format code the actor doesn't recognize
- `firstShown`, `lastShown` — the date range Google recorded the ad as active
- `previewUrl` — a link to preview the ad creative (an image link for text and image ads, a preview link for video ads)
- `imageUrl` — direct image URL, image-format ads only
- `videoUrl` — direct video file URL for video ads when it can be resolved; always `null` with `skipDetails` on
- `adLibraryUrl` — direct link to this ad on the Ads Transparency Center
- `startUrl` — the input advertiser URL that produced this ad (`null` for ads found via `searchTerms`)
- `searchTerm` — the search term that found this advertiser (`null` for ads from `startUrls`)
- `scrapedAt` — when the actor fetched the record

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `startUrls` | array | – | Direct Google Ads Transparency Center advertiser URLs, e.g. `https://adstransparency.google.com/advertiser/AR08888592736429539329`. A `?region=` in the URL is ignored; use `region` instead. |
| `searchTerms` | array | – | Advertiser names or domains to search for instead of a direct URL. Each term is resolved to a single advertiser. |
| `region` | string | `anywhere` | Only return ads shown in this country; `anywhere` applies no region filter. Applies to every advertiser in the run. |
| `resultsLimit` | integer | `50` | Maximum ads to return per advertiser (1–1000). |
| `skipDetails` | boolean | `false` | Skip the per-ad detail fetch for a faster run; records come from the advertiser's ad list and never include `videoUrl`. |

At least one of `startUrls` or `searchTerms` must be provided.

### Example: look up an advertiser by domain

```json
{
  "searchTerms": ["nike.com"],
  "resultsLimit": 100
}
```

### Example: scrape a known advertiser's URL directly

```json
{
  "startUrls": [
    { "url": "https://adstransparency.google.com/advertiser/AR08888592736429539329?region=ES" }
  ]
}
```

### Example: quick list-only scan filtered to one country

```json
{
  "searchTerms": ["Amazon"],
  "region": "US",
  "resultsLimit": 200,
  "skipDetails": true
}
```

### Use cases

- **Competitive ad monitoring** — track which creatives a competitor is currently running and for how long
- **Creative research** — pull a brand's historical ad formats and preview media for inspiration
- **Compliance review** — check whether an advertiser's ads ran in a region they shouldn't have targeted
- **Agency reporting** — build a client or prospect's ad history into a pitch deck or audit
- **Ad format analysis** — compare how many of an advertiser's creatives are text, image, or video

### FAQ

**What's the difference between `startUrls` and `searchTerms`?**
`startUrls` points directly at an advertiser's existing Transparency Center page. `searchTerms` looks up the advertiser by name or domain first, then scrapes their page — use it when you don't already have the direct URL. For a domain, the actor uses the advertiser Google links to that exact domain when there is one; otherwise, and for names, it picks the matching advertiser with the most ads. Terms that match no advertiser are skipped.

**Why are `imageUrl` or `videoUrl` null on some ads?**
`imageUrl` is only populated for image-format ads, and `videoUrl` only for video ads whose video file can be resolved. Other formats simply don't have that field, and both are `null` when Google doesn't expose the media.

**What does `skipDetails` change?**
With `skipDetails` enabled, the actor doesn't open each ad's own detail record. It still returns the ID, format, dates, preview link and (for image ads) image URL from the advertiser's ad list, but `videoUrl` stays `null` and dates come only from the list. With it off, ads whose details can't be loaded are left out.

**Can I filter by country?**
Yes, set `region` to a country; results are limited to ads Google recorded as shown in that country. Leave it as `anywhere` for no filter.

**How many ads can I get per advertiser?**
Up to `resultsLimit` (1,000 at most) per advertiser, limited by how many creatives the Transparency Center actually has on record for that advertiser in the chosen region.

**Is this affiliated with Google?**
No. This is an independent, third-party actor that reads the publicly accessible Google Ads Transparency Center; it is not affiliated with or endorsed by Google.

# Actor input Schema

## `startUrls` (type: `array`):

Direct Google Ads Transparency Center advertiser URLs. Each URL must start with "https://adstransparency.google.com/advertiser/..."

## `searchTerms` (type: `array`):

Keywords or domain names to search for advertisers in the Google Ads Transparency Center (e.g., "Google LLC", "nike.com").

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

Filter ads by the region where they were shown.

## `resultsLimit` (type: `integer`):

Maximum number of ads to extract per advertiser.

## `skipDetails` (type: `boolean`):

If enabled, the scraper will not fetch full details for each ad. This is much faster but returns less information per ad.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://adstransparency.google.com/advertiser/AR08888592736429539329?region=ES"
    }
  ],
  "searchTerms": [
    "Google LLC"
  ],
  "region": "anywhere",
  "resultsLimit": 50,
  "skipDetails": false
}
```

# Actor output Schema

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

Dataset containing all scraped Google ads with advertiser info, dates, and preview URLs

# 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 = {
    "startUrls": [
        {
            "url": "https://adstransparency.google.com/advertiser/AR08888592736429539329?region=ES"
        }
    ],
    "searchTerms": [
        "Google LLC"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/google-ads-advertiser-creative-history-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 = {
    "startUrls": [{ "url": "https://adstransparency.google.com/advertiser/AR08888592736429539329?region=ES" }],
    "searchTerms": ["Google LLC"],
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/google-ads-advertiser-creative-history-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 '{
  "startUrls": [
    {
      "url": "https://adstransparency.google.com/advertiser/AR08888592736429539329?region=ES"
    }
  ],
  "searchTerms": [
    "Google LLC"
  ]
}' |
apify call nimbryxo-studio/google-ads-advertiser-creative-history-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/google-ads-advertiser-creative-history-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/9wEoeBWrpFtgDeTGz/builds/BfHmQ5MMSufDCkZFQ/openapi.json