# Google Ads Metadata Scraper (`googleapi/google-ads-metadata-scraper`) Actor

Extract rich public advertiser and creative metadata from the official Google Ads Transparency Center with bounded rendered-page support and pure business dataset rows.

- **URL**: https://apify.com/googleapi/google-ads-metadata-scraper.md
- **Developed by:** [Google API](https://apify.com/googleapi) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 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/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 Metadata Scraper

Extract public advertiser and creative metadata from the official [Google Ads Transparency Center](https://adstransparency.google.com/). The Actor reads the public search, advertiser, and creative-detail pages and returns fields that the page actually exposes.

### What it is useful for

- Building a public competitor-ad library keyed by advertiser and creative IDs.
- Reviewing public ad formats, platforms, regions, media previews, and last-shown dates.
- Re-running bounded advertiser searches for market or creative research.

The Actor does not access Google Ads accounts, private APIs, private targeting settings, spend, conversion, payment data, credentials, or personal/contact data.

### Inputs

#### Search by advertiser

Provide a public advertiser name or website. The Actor enters it into the Center's public search and selects the matching public advertiser result.

```json
{
  "searchQuery": "Nike",
  "maxItems": 25,
  "maxPages": 3,
  "includeMedia": true
}
```

`advertiserName` and `q` are accepted aliases. Use `queries` or `searchKeywords` for several searches.

#### Inspect public URLs

Use `startUrls` for public Center home, advertiser, or creative URLs. `sourceUrls`, `urls`, `url`, and `sourceUrl` are accepted compatibility aliases. Custom URLs take precedence over generated searches.

```json
{
  "startUrls": [
    { "url": "https://adstransparency.google.com/advertiser/AR16735076323512287233?platform=SEARCH&region=US&safe=active" }
  ],
  "maxItems": 50,
  "sortBy": "advertiser_name_asc"
}
```

Only `adstransparency.google.com` public routes are accepted. Private RPC endpoints and sensitive query parameters are rejected.

Direct creative URLs return the matching creative rather than requiring a gallery card. Creative text and `creativeHtml` come from the currently visible official preview. Unobserved copy remains null; a preview image is not treated as text.

#### Filtering and limits

`maxItems` is the global normal-row limit. `page` selects a one-based advertiser-results page (1–20) for generated searches; direct URLs start at their supplied listing and use `maxPages` for bounded creative-grid scrolling. `maxPages` bounds those scroll rounds per source. `deduplicate` removes repeated creative IDs across sources. Optional filters are `platform`, `region`, `adFormat`, `filterAdvertiserName`, and `verifiedOnly`. Sorting supports `source`, `advertiser_name_asc`, `creative_id_asc`, and `format`.

```json
{
  "searchQuery": "Nike",
  "platform": "SEARCH",
  "region": "US",
  "adFormat": "TEXT",
  "verifiedOnly": true,
  "maxItems": 20
}
```

### Collection behavior

The Actor reads public pages from the Google Ads Transparency Center. If Google presents an access challenge or an unavailable page, the run summary and logs report it; the Actor does not bypass the challenge.

`includeCreativeDetails` opens public creative pages to enrich fields exposed by the detail view, including format, shown-in region, last-shown date, variation counts, media, rating, delivery, and destination text. It is disabled by default because it adds one bounded page request per inspected row, up to `maxItems` across the run.

When a public creative detail page displays country-dependent transparency disclosures, the Actor also preserves its targeting-information line, recipient-total wording, and subject-matter label. These stay `null` unless the corresponding labeled value is visibly present; the page's region filter is not treated as targeting evidence, and recipient text is not converted into an inferred count. Google says these extra disclosures are available only for ads served in certain locations.

Selecting the `adFormat` filter or `sortBy: "format"` automatically opens the needed public detail pages even when `includeCreativeDetails` is false. This makes format filtering and sorting use Google's source-reported format instead of silently treating an uninspected card as a non-match. These reads share the global `maxItems` detail-page cap; once it is used, no more format-dependent records are inspected. If a detail page does not expose a format, it remains unknown and does not match a specific format filter. With neither the detail toggle nor a format filter/sort selected, no creative detail pages are fetched by default. Preview images and videos are reported as media assets, not used to guess the official ad format; Google may render a text ad inside an image.

### Output

Each normal row is pure public business data and can include:

- Advertiser name, ID, public profile URL, legal name, country, approximate public ad count, and verified marker.
- Creative ID, canonical URL, public format, platform, region, ad label, grid position, and variation details.
- Creative text/headline/description when the public DOM exposes them as text, destination display text/domain, rating and delivery claims. Rasterized creative previews are represented by approved media URLs and dimensions; text is not guessed or OCR-inferred.
- Approved Google-hosted media URLs, dimensions, last-shown text/date, and precision marker.
- Public, region-dependent targeting, recipient-total, and subject-matter disclosures, only when shown on the creative page.

Fields are included only when the public source provides them; unknown details are not inferred. The run summary and source diagnostics are available separately from the dataset in the Output tab.

`lastShown` and `lastShownText` preserve Google's displayed wording. `lastShownDate` is populated only when the source text contains an explicit year; a yearless value such as `Sep 1` remains raw, while its normalized date and estimated-ness fields stay `null` rather than inventing a year.

#### Example output

The following is shaped from the live Chrome check of Nike's public advertiser and creative pages. Values such as the advertiser profile, `Advertisement (1 of 80)`, `Shown in the United States`, `Last shown: Sep 1, 2026`, `Format: Image`, and `1 of 3 variations` are preserved only when Google exposes them. Unknown media URLs, destinations, ratings, and delivery claims stay absent rather than being guessed.

```json
{
  "advertiserName": "Nike, Inc.",
  "advertiserId": "AR16735076323512287233",
  "advertiserUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233?platform=SEARCH&region=US&safe=active",
  "advertiserLegalName": "Nike, Inc.",
  "advertiserBasedIn": "the United States",
  "advertiserBasedInCountryCode": "US",
  "advertiserAdCountEstimate": 9000,
  "advertiserAdCountIsApproximate": true,
  "advertiserVerified": true,
  "advertiserVerifiedLabel": "Verified",
  "creativeId": "CR03857847523435610113",
  "creativeUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR03857847523435610113?platform=SEARCH&region=US&safe=active",
  "canonicalUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR03857847523435610113?platform=SEARCH&region=US&safe=active",
  "adFormat": "IMAGE",
  "adFormatText": "Image",
  "platform": "SEARCH",
  "platformName": "Google Search",
  "region": "US",
  "regionName": "the United States",
  "targetingInformationText": null,
  "recipientCountText": null,
  "subjectMatterLabel": null,
  "adLabel": "Advertisement (1 of 80)",
  "gridPosition": 1,
  "gridTotal": 80,
  "variationPosition": 1,
  "variationCount": 3,
  "variationText": "1 of 3 variations",
  "creativeText": "Nike Hyperdiamond 4 Keystone Big Kids' Softball Cleats in Pink, Size: 13C | FZ8655-600 [Price]\\nNike",
  "creativeHeadline": null,
  "creativeHtml": null,
  "creativeDescription": null,
  "creativeImageUrl": null,
  "creativeVideoUrl": null,
  "creativeImageAlt": null,
  "creativeImageWidth": null,
  "creativeImageHeight": null,
  "creativeImageAspectRatio": null,
  "mediaType": null,
  "mediaCount": 0,
  "hasImage": null,
  "hasVideo": null,
  "creativeAssetHost": null,
  "isMultiVariation": true,
  "listingPageType": "advertiser",
  "lastShown": "Sep 1, 2026",
  "lastShownText": "Sep 1, 2026",
  "lastShownDate": "2026-09-01",
  "lastShownIsEstimated": false,
  "destinationDisplayUrl": null,
  "destinationDomain": null,
  "ratingValue": null,
  "ratingCount": null,
  "deliveryClaim": null,
  "adTopic": null,
  "audienceSelection": null,
  "firstShownText": null,
  "firstShownDate": null,
  "shownCountText": null,
  "shownCountMin": null,
  "shownCountMax": null,
  "impressionsStartDate": null,
  "impressionsEndDate": null,
  "timesShownAvailableFromDate": null
}
```

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

### Cost and limitations

No paid Google Ads API is required. Apify compute and storage usage depend on the number of sources, scroll rounds, and optional creative-detail pages. The public Center can change its UI, omit older ads by region/platform, or return access boundaries; the Actor reports those states instead of guessing.

### Legal and responsible use

Use the Actor only for lawful public-interest research and in accordance with Google's terms, applicable privacy rules, and the rights of advertisers and publishers. Keep request limits reasonable and do not use the output to infer private audiences or sensitive personal information.

Regional disclosure fields preserve Google's labeled ad topic, first-shown calendar date, audience-category inclusion/exclusion, and actual impression reporting window when visible. These are unknown (`null`) otherwise. The source's reporting window is not substituted with last-shown dates.

# Actor input Schema

## `searchQuery` (type: `string`):

Public advertiser name or website to enter into the Center search when no custom source URL is supplied.

## `advertiserName` (type: `string`):

Compatibility alias for searchQuery.

## `q` (type: `string`):

Compatibility alias for searchQuery.

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

Up to 20 public advertiser searches. Ignored when custom source URLs are supplied.

## `searchKeywords` (type: `array`):

Compatibility alias for queries; a single string is also accepted by the runtime.

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

Public official Center home, search-results, advertiser, or creative URLs. Custom URLs override generated searches.

## `sourceUrls` (type: `array`):

Compatibility alias for startUrls.

## `urls` (type: `array`):

Compatibility alias for startUrls.

## `url` (type: `string`):

Compatibility alias for one public source URL.

## `sourceUrl` (type: `string`):

Compatibility alias for one public source URL.

## `maxItems` (type: `integer`):

Global maximum of normal advertiser/creative rows. Diagnostics do not count.

## `maxResults` (type: `integer`):

Compatibility alias for maxItems.

## `maxPages` (type: `integer`):

Maximum bounded page-scroll rounds per source while public creative cards are collected.

## `deduplicate` (type: `boolean`):

Remove duplicate creative IDs across sources and scroll rounds.

## `platform` (type: `string`):

Optional exact public platform filter such as SEARCH, YOUTUBE, or DISPLAY.

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

Optional exact public region filter such as US.

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

Compatibility alias for region.

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

Optional exact public format filter such as TEXT, IMAGE, or VIDEO. Selecting this filter automatically opens up to maxItems public creative detail pages so format can be read from the source.

## `filterAdvertiserName` (type: `string`):

Keep rows whose public advertiser name contains this case-insensitive text.

## `advertiserNameFilter` (type: `string`):

Compatibility alias for filterAdvertiserName.

## `verifiedOnly` (type: `boolean`):

Keep only cards that publicly expose the Center's verified advertiser marker.

## `sortBy` (type: `string`):

Global stable order after collection and filtering. Selecting format sorting automatically opens up to maxItems public creative detail pages so source-reported formats are available.

## `includeMedia` (type: `boolean`):

Include approved Google-hosted image/video URLs and dimensions exposed by the public creative preview.

## `includeCreativeDetails` (type: `boolean`):

Visit public creative detail pages to enrich format, last-shown date, variation count, and media fields. Off by default; an adFormat filter or format sort still triggers the bounded detail reads needed for that choice.

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

Optional Apify proxy configuration for public Google requests.

## `page` (type: `integer`):

One-based advertiser-results page used with a generated search. For a direct advertiser URL, use maxPages to scroll its creative listing.

## Actor input object example

```json
{
  "startUrls": [],
  "maxItems": 25,
  "maxPages": 5,
  "deduplicate": true,
  "verifiedOnly": false,
  "sortBy": "source",
  "includeMedia": true,
  "includeCreativeDetails": false,
  "page": 1
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `output` (type: `string`):

No description

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

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

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

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,googleapi/google-ads-metadata-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/LyxVMR3Pqunwn1TbC/builds/1gU6cZMj4Y6Hp3mdC/openapi.json