# Google Ads Transparency Pro API (`zenomastro/google-ads-transparency-pro`) Actor

Google Ads Transparency Center scraper for brands, domains and advertiser IDs with creatives, dates, previews, reach, platforms and targeting.

- **URL**: https://apify.com/zenomastro/google-ads-transparency-pro.md
- **Developed by:** [Rosario Vitale](https://apify.com/zenomastro) (community)
- **Categories:** Marketing, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 ad results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 Transparency Pro API

Search the Google Ads Transparency Center by **brand**, **verified advertiser ID/URL**, or **advertised domain** and return structured ad creatives ready for competitor research, ad intelligence, monitoring, and data pipelines.

The Actor uses Google's public Transparency Center RPC endpoints directly. It does **not** require a browser for the normal extraction path.

### Why this Actor?

Google Ads Transparency can be difficult to automate reliably: brand names may resolve to several legal advertisers, search results are paginated, country filters use numeric region identifiers, creative details live behind a second lookup call, and external changes can produce empty or confusing outputs.

This Actor is designed around predictable, auditable behavior:

- Brand / legal advertiser search with scored resolution
- Direct advertiser IDs and Transparency Center URLs
- Advertised-domain search when the legal advertiser name is unknown
- Country filtering for virtually all ISO 3166-1 alpha-2 countries
- Automatic pagination instead of returning only the first page
- Duplicate creative removal
- Image, video, text, and unknown-format filtering
- First/last shown dates and days active
- Advertiser verification/legal-name lookup
- Creative preview/content URLs
- Optional detailed creative enrichment
- Optional date window filtering
- Bounded retries and timeouts
- Optional proxy rotation
- Diagnostic failure rows are not charged
- Stops cleanly at the user's maximum charge limit

### Input examples

#### Search by brand

```json
{
  "queries": ["Nike"],
  "region": "US",
  "maxAdsPerAdvertiser": 100,
  "detailLevel": "basic"
}
```

#### Search by advertiser URL

```json
{
  "advertiserUrls": [
    "https://adstransparency.google.com/advertiser/AR16735076323512287233"
  ],
  "region": "US",
  "detailLevel": "detailed"
}
```

#### Search by advertised domain

```json
{
  "domains": ["nike.com"],
  "region": "US",
  "maxAdsPerAdvertiser": 50
}
```

### Advertiser resolution

For text queries, the Actor reads Google Ads Transparency suggestions and scores candidates using:

1. normalized exact/partial name match,
2. requested country match,
3. approximate ad-volume signal.

The selected advertiser is then verified with Google's advertiser lookup endpoint. Enable **Include advertiser resolution candidates** to include the candidate list used for ambiguous brands.

For maximum precision in recurring workflows, supply a known `AR...` advertiser ID or Transparency Center advertiser URL.

### Basic vs detailed mode

**Basic** returns the core creative row: advertiser, creative ID, format, first/last shown dates, days active, content/preview URL, and Transparency Center URL.

**Detailed** performs an additional creative lookup. When Google exposes the data, it can add:

- additional creative/content variants,
- region reach information,
- platform breakdowns,
- targeting flags,
- topic/category information.

If a detail lookup fails while the base ad is valid, the Actor returns the base ad with `detailAvailable: false` and charges it at the basic rate instead of failing or overcharging.

### Pricing

- **Basic ad:** $0.0015 per successful ad row — about **$1.50 / 1,000 ads**
- **Detailed ad:** $0.0022 per successfully enriched ad row — about **$2.20 / 1,000 ads**
- A small Actor-start charge is shown in the Apify pricing panel.

Resolution/search errors are useful diagnostic rows and are **not** charged as ad results.

The pricing is positioned around the active Google Ads Transparency market rather than artificially undercutting it.

### Country support

Input uses normal two-letter ISO codes such as `US`, `IT`, `GB`, `DE`, `FR`, `CA`, `AU`, `JP`, or `BR`.

The Actor derives Google's numeric country identifier from ISO/M49 data, avoiding a short hardcoded country list.

### Date and format filters

Use `formats` to keep only `image`, `video`, `text`, or `unknown` creatives.

Use `dateFrom` and `dateTo` with ISO dates such as `2026-01-01`. Filtering is applied to the first/last shown timestamps returned by Google.

### Reliability

Requests use bounded timeouts and retry temporary network failures, HTTP 403/408/425/429 responses, and server errors. Direct requests are the default to avoid unnecessary proxy cost.

If Google begins limiting a run, enable **Proxy configuration**. The Actor can rotate proxy sessions between retry attempts.

Google Ads Transparency uses undocumented public RPC endpoints. They can change without notice, so the Actor uses defensive parsing and emits explicit errors instead of silently returning bad rows.

### Output

Successful rows use `recordType: "ad"` and include a direct Transparency Center URL for the creative.

Resolution and search failures use `success: false` with a structured `errorType` and concise `error` message. They remain in the Dataset for debugging but are not billed as ads.

### Responsible use

This Actor reads public advertising-transparency data. Use the output in accordance with applicable privacy, copyright, advertising, and platform rules.

### Support

For a reproducible problem, include the run ID, query/advertiser ID, region, and whether a proxy was enabled. Never include API tokens or proxy credentials in an issue.

# Actor input Schema

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

Brand names, legal advertiser names, or search terms to resolve through Google Ads Transparency suggestions.

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

Optional Google Ads Transparency advertiser IDs beginning with AR.

## `advertiserUrls` (type: `array`):

Optional adstransparency.google.com advertiser URLs. The AR advertiser ID is extracted automatically.

## `domains` (type: `array`):

Optional domains such as nike.com. Domain search can find creatives even when the advertiser legal name is unknown.

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

ISO 3166-1 alpha-2 country code such as US, IT, GB, DE, FR, CA, AU, JP. Most countries are supported.

## `maxAdvertisers` (type: `integer`):

Maximum unique advertisers resolved across all query inputs.

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

Maximum unique creatives returned for each resolved advertiser or domain. Results are paginated automatically.

## `detailLevel` (type: `string`):

Basic returns the core creative row. Detailed additionally calls the creative lookup endpoint for content variants, reach/platform data, targeting flags, and topic when Google exposes them.

## `formats` (type: `array`):

Optional format filter. Leave empty for all formats.

## `dateFrom` (type: `string`):

Optional ISO date such as 2026-01-01. Ads whose last shown date is earlier are filtered out.

## `dateTo` (type: `string`):

Optional ISO date such as 2026-12-31. Ads whose first shown date is later are filtered out.

## `includeResolutionCandidates` (type: `boolean`):

Attach up to 10 advertiser candidates used when resolving a brand/search query. Useful for audits and ambiguous brands.

## `requestTimeoutSecs` (type: `integer`):

Per-request timeout for Google Ads Transparency RPC calls.

## `retries` (type: `integer`):

Retries temporary 403/408/425/429/5xx and network failures with bounded backoff.

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

Optional Apify/custom proxy rotation. Direct requests are used by default.

## Actor input object example

```json
{
  "queries": [
    "Nike"
  ],
  "advertiserIds": [],
  "advertiserUrls": [],
  "domains": [],
  "region": "US",
  "maxAdvertisers": 5,
  "maxAdsPerAdvertiser": 100,
  "detailLevel": "basic",
  "formats": [],
  "dateFrom": "",
  "dateTo": "",
  "includeResolutionCandidates": false,
  "requestTimeoutSecs": 20,
  "retries": 2,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (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("zenomastro/google-ads-transparency-pro").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("zenomastro/google-ads-transparency-pro").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 zenomastro/google-ads-transparency-pro --silent --output-dataset

```

## MCP server setup

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

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/cOOA4Jd57DkeKkSUi/builds/qrLgHuxAIaCNF2P0N/openapi.json