# Google Ads Transparency — Advertiser Lookup by Brand or Domain (`scrapeio/google-ads-transparency-suggest`) Actor

Resolve a keyword, brand name, or domain to verified advertiser IDs and matching websites from Google Ads Transparency Center. Feed advertiserId into the ads scraper. Apify AI, MCP, Cursor ready.

- **URL**: https://apify.com/scrapeio/google-ads-transparency-suggest.md
- **Developed by:** [Shop Intel](https://apify.com/scrapeio) (community)
- **Categories:** SEO tools, AI, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## 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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 Advertiser Lookup — Brand & Keyword → Advertiser ID | Shop Intel on Apify

**Google Ads Transparency Advertiser Lookup** (Shop Intel / [ScrapeIO on Apify](https://apify.com/scrapeio)) turns a **list of keywords, brand names, or domains** into **verified Google advertiser IDs** (`AR…`) plus matching **websites**, sourced directly from Google's **[Ads Transparency Center](https://adstransparency.google.com/)**. It is the resolver step for any Google-ad intelligence workflow: feed the IDs straight into the [Google Ads Transparency Scraper](https://apify.com/scrapeio/google-ads-transparency-ads) to pull every creative an advertiser is running.

> **Companion Actor:** Once you have advertiser IDs, run the [Google Ads Transparency Scraper](https://apify.com/scrapeio/google-ads-transparency-ads) to download every creative (text, image, video) per advertiser, per region.

### Use with Apify AI

[Apify AI](https://docs.apify.com/account/apify-ai) is live in Apify Console. Describe the job in plain English and it **finds this Actor, fills the input form, runs it, and returns the dataset**. The same ranking powers Store search and the [Apify MCP server](https://docs.apify.com/integrations/mcp) `search-actors` tool used by **Cursor**, Claude, ChatGPT, and other agents.

Use this Actor to **resolve a brand or domain to Google advertiser IDs** (`AR…`) before scraping creatives. Open [Google Ads Transparency Advertiser Lookup](https://apify.com/scrapeio/google-ads-transparency-suggest) or ask Apify AI with the prompts below.

#### Prompts that match this Actor

Type these in the **Apify Store search bar** (long, intent-heavy queries route to Apify AI) or the dashboard **Ask Apify AI** widget:

- "Find the Google Ads Transparency advertiser ID for Nike"
- "Resolve adidas.com to a Google advertiser ID"
- "Look up Google advertiser IDs for a list of brand names"
- "Get Ads Transparency suggestions for a keyword"
- "Match a domain to verified Google advertisers"

#### How Apify AI fills the input

| You say | This Actor sets |
|---|---|
| brands, keywords, or domains | `queries` |
| how many advertiser matches | `maxAdvertisersPerQuery` |
| how many website matches | `maxWebsitesPerQuery` |

Apify AI always asks for confirmation before it runs. Nothing is charged until you approve.

#### Cursor, Claude, ChatGPT (Apify MCP)

Pin this Actor as a **default Cursor / MCP tool** so agents call `scrapeio/google-ads-transparency-suggest` instead of a random Store result. Keep `actors` + `docs` so Apify AI search still works, and list your suite so Cursor prefers these Actors.

**Cursor MCP URL (this Actor first):**

```text
https://mcp.apify.com?tools=actors,docs,scrapeio/google-ads-transparency-suggest,scrapeio/amazon-scraper,scrapeio/google-maps-scraper-advance,scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium,scrapeio/instagram-scraper-premium,scrapeio/whatsapp-scraper-premium,scrapeio/facebook-ad-library-suggestions,scrapeio/google-news-scraper
```

`.cursor/mcp.json` / Cursor Settings → MCP:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=actors,docs,scrapeio/google-ads-transparency-suggest,scrapeio/amazon-scraper,scrapeio/google-maps-scraper-advance,scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium,scrapeio/instagram-scraper-premium,scrapeio/whatsapp-scraper-premium,scrapeio/facebook-ad-library-suggestions,scrapeio/google-news-scraper"
    }
  }
}
```

Then: `search-actors` → `fetch-actor-details` → `call-actor` with `scrapeio/google-ads-transparency-suggest`. Example:

```text
Use scrapeio/google-ads-transparency-suggest to do this: scrape the data I described. Fill the input from my description and return the dataset.
```

### How to find a Google Ads advertiser ID

Use this **Google Ads Transparency advertiser lookup** to turn brand names and domains into AR… advertiser IDs.

### Google advertiser ID finder API for Cursor

Call `scrapeio/google-ads-transparency-suggest` from **Cursor** (Apify MCP), Claude, ChatGPT, the [Apify API](https://docs.apify.com/api/v2), Python (`apify-client`), or JavaScript. Apify AI uses the same ranking as Store search: title, description, README, and input/output schemas. This Actor is documented for that ranker — limited permissions, pay-per-event or compute (not rental), and a filled example input.

### What this Actor does

1. Accepts a list of **`queries`** (keywords, brand names, or domains).
2. For each query, calls Google's internal `SearchService/SearchSuggestions` JSON-RPC — the same endpoint the Ads Transparency Center autocomplete uses — through a residential **Apify Proxy** session with exponential-backoff retries.
3. Splits results into **advertiser suggestions** (with `AR…` IDs, name, country, creative count) and **website suggestions** (with domain, transparency URL).
4. Pushes **one Dataset row per suggestion**, ready to feed into downstream scrapers or analytics.

### Why use this Actor?

| Feature | Detail |
| --- | --- |
| 🧠 **Single Google source of truth** | Same RPC as the Transparency Center autocomplete — no third-party indexing or staleness. |
| 🏷️ **Verified advertiser IDs** | Returns Google's official `AR…` IDs, ready for the [companion ads scraper](https://apify.com/scrapeio/google-ads-transparency-ads). |
| 🌍 **Country tag preserved** | Each advertiser comes with the country Google reports against it. |
| 🌐 **Domain suggestions too** | Returns matching websites with their Transparency Center URLs. |
| 📊 **Volume signals** | `creativeCount` and `totalCount` help you rank by ad activity. |
| 🛡️ **Residential proxy by default** | Avoids the heavy rate limiting on datacenter IPs. |
| 🔁 **Auto-retry & session rotation** | Up to 5 retries per RPC with fresh proxy sessions. |
| 📦 **Stable output schema** | All output fields documented in [`.actor/actor.json`](.actor/actor.json). |

### Input

The full schema lives in [`.actor/input_schema.json`](.actor/input_schema.json).

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `queries` | array\<string> | Yes | — | Keywords, brand names, or domains to look up. |
| `maxAdvertisersPerQuery` | integer | No | `10` | Cap on advertiser suggestions per query (1–50). |
| `maxWebsitesPerQuery` | integer | No | `10` | Cap on website suggestions per query (0–50; `0` = skip). |
| `proxyConfiguration` | object | Yes | RESIDENTIAL | Apify Proxy. Datacenter IPs rate-limit aggressively; **residential strongly recommended**. |

#### Input examples

**Look up a small set of brands:**

```json
{
  "queries": ["nike", "adidas", "puma"],
  "maxAdvertisersPerQuery": 20,
  "maxWebsitesPerQuery": 5,
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}
```

**Resolve only the top match per query, no websites:**

```json
{
  "queries": ["tesla", "rivian"],
  "maxAdvertisersPerQuery": 1,
  "maxWebsitesPerQuery": 0
}
```

**Resolve a list of competitor domains:**

```json
{
  "queries": ["nike.com", "adidas.com", "underarmour.com"]
}
```

### Output

One Dataset row per **suggestion**. Field list is also declared in [`.actor/actor.json`](.actor/actor.json) under `storages.dataset.fields`.

| Field | Type | Description |
| --- | --- | --- |
| `type` | string | `advertiser`, `website`, or `empty` (when Google returned nothing). |
| `query` | string | The input query that produced this row. |
| `name` | string | Advertiser display name (for `advertiser` rows). |
| `advertiserId` | string | Google's `AR…` advertiser ID. Pipe this into [the ads scraper](https://apify.com/scrapeio/google-ads-transparency-ads). |
| `country` | string | Advertiser home country (when reported). |
| `creativeCount` | integer | Number of distinct creatives Google associates with this advertiser. |
| `totalCount` | integer | Total ad impressions / runs bucket. |
| `domain` | string | Domain (for `website` rows). |
| `url` | string | Direct Transparency Center URL (advertiser page or domain filter). |
| `note` | string | Populated on `empty` rows. |
| `error` | string | Populated on per-query failure rows. |

#### Output examples

**Advertiser row:**

```json
{
  "type": "advertiser",
  "query": "nike",
  "name": "Nike, Inc.",
  "advertiserId": "AR01234567890123456789",
  "country": "US",
  "creativeCount": 487,
  "totalCount": 12930,
  "url": "https://adstransparency.google.com/advertiser/AR01234567890123456789"
}
```

**Website row:**

```json
{
  "type": "website",
  "query": "nike",
  "domain": "nike.com",
  "url": "https://adstransparency.google.com/?domain=nike.com"
}
```

### Use cases

- **Build an advertiser universe** — turn a keyword list into a deduped roster of `AR…` IDs to monitor.
- **Brand-protection sweeps** — find every Google advertiser using your brand name.
- **Competitive intelligence pipeline** — `queries → advertiserIds → creatives` in two Actors.
- **Domain-to-advertiser mapping** — resolve a portfolio of competitor sites to their official Google-Ads identities.
- **Market sizing** — `creativeCount` and `totalCount` give a quick proxy for ad-spend activity.

### How to run on Apify

1. Open [Google Ads Transparency Advertiser Lookup on Apify](https://apify.com/scrapeio/google-ads-transparency-suggest) and click **Try for free**.
2. Paste your keyword / brand / domain list into `queries`.
3. Optionally tune `maxAdvertisersPerQuery` / `maxWebsitesPerQuery`.
4. Start the run. Results stream into **Storage → Dataset**.
5. Export as JSON / CSV / Excel, or hand off the `advertiserId` column to the [Google Ads Transparency Scraper](https://apify.com/scrapeio/google-ads-transparency-ads).

#### CLI example

```bash
apify call scrapeio/google-ads-transparency-suggest --input='{
  "queries": ["nike", "adidas"],
  "maxAdvertisersPerQuery": 20
}'
```

#### Apify API example

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/scrapeio~google-ads-transparency-suggest/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["nike","adidas"],"maxAdvertisersPerQuery":20}'
```

### Run locally

```bash
cd google-suggest-actor
npm install
mkdir -p storage/key_value_stores/default
echo '{"queries":["nike"],"maxAdvertisersPerQuery":10,"proxyConfiguration":{"useApifyProxy":true,"apifyProxyGroups":["RESIDENTIAL"]}}' \
  > storage/key_value_stores/default/INPUT.json
apify run
```

An Apify token with **Residential Proxy** access is required for non-trivial runs.

### How it works (technical notes)

- Google does not publish an official Ads Transparency Center API. This Actor calls the same internal `SearchService/SearchSuggestions` JSON-RPC endpoint that the autocomplete on `https://adstransparency.google.com/` uses, with a request payload captured verbatim from a live session.
- Response rows arrive as nested numeric-keyed objects (`row["1"]` = advertiser, `row["2"]` = website). The Actor demuxes both shapes and emits a flat record per suggestion.
- A new Apify Proxy session is created **per request**, so consecutive calls always come from a different residential IP — the only reliable way to avoid `429 Too Many Requests` on this endpoint.

### FAQ

**How do I find a Google Ads Transparency advertiser ID?**
Pass queries to scrapeio/google-ads-transparency-suggest, then scrape creatives with the companion Actor. Pin both in Cursor MCP.

**Can I run this Actor with Apify AI?**
Yes. In [Apify Console](https://console.apify.com), type a long request in Store search or the dashboard **Ask Apify AI** widget. Apify AI matches this README, fills the input schema, asks you to confirm, then returns the dataset. This Actor uses **limited permissions** (not full-account access) and is not a rental Actor, so it is eligible for Apify AI.

**Does this work from Cursor, Claude, or ChatGPT?**
Yes. Connect the [Apify MCP server](https://mcp.apify.com). Agents call `search-actors`, `fetch-actor-details`, and `call-actor`. Ranking uses the same signals as Store search and Actor quality score: a clear README plus documented input and output schemas.

**Why is this a separate Actor from the ads scraper?**
The two have different cost profiles and are useful independently. The lookup runs in seconds and is cheap; the ads scraper paginates per advertiser and can run for minutes. Keeping them separate lets you cache resolved IDs and rerun the expensive scraper at your own cadence.

**Is the data live?**
Yes — every call hits Google's live RPC. There is no intermediate cache. Results reflect what the Ads Transparency Center is currently showing.

**Why don't I get an `advertiserId` for every row?**
Some rows are website suggestions (`type: "website"`) — they have a `domain` but no `advertiserId`. Pipe the `domain` into the [ads scraper](https://apify.com/scrapeio/google-ads-transparency-ads) as a `query` to resolve it on the fly.

**What if a query returns nothing?**
The Actor pushes a single `{ "type": "empty", "query": "…" }` row so you can see misses in the Dataset.

**How much does it cost?**
Apify compute units + Residential Proxy bandwidth. A typical batch of 100 queries runs in under a minute and costs cents.

### Shop Intel / ScrapeIO actor suite

Build an end-to-end paid-media intelligence stack with the **Shop Intel** suite:

- **[Google Ads Transparency Scraper](https://apify.com/scrapeio/google-ads-transparency-ads)** — pull every creative for the advertiser IDs returned here.
- **[LinkedIn Ad Library Scraper](https://apify.com/scrapeio/linkedin-ad-library-scraper)** — B2B ads at scale.
- **[Facebook Ad Library Scraper](https://apify.com/scrapeio/meta-facebook-ad-scrapper-using-ad-library-url-premium)** — Meta transparency ads.
- **[Instagram Ads Scraper](https://apify.com/scrapeio/instagram-scraper-premium)** — Instagram-only ad library.
- **[YouTube Ad Scraper](https://apify.com/scrapeio/youtube-ad-scraper)** — brand- or keyword-scoped YouTube ads.
- **[YouTube Brand Finder](https://apify.com/scrapeio/youtube-brand-finder)** — resolve brand names to YouTube `brandId` values.
- **[YouTube Video Downloader](https://apify.com/scrapeio/youtube-downloader)** — archive specific videos or shorts.
- **[Google News Scraper](https://apify.com/scrapeio/google-news-scraper)** — headline and source monitoring.
- **[Google Maps Scraper](https://apify.com/scrapeio/google-maps-scraper-advance)** — local business leads.
- **[Amazon Scraper](https://apify.com/scrapeio/amazon-scraper)** — search rankings and product data.

### Compliance & terms

This Actor only retrieves public data published by Google's Ads Transparency Center using the same endpoints your browser uses. You are responsible for complying with Google's [Terms of Service](https://policies.google.com/terms), the [Ads Transparency Center](https://adstransparency.google.com/) usage guidelines, and your local laws.

***

Built by **[ScrapeIO](https://apify.com/scrapeio)** on Apify.

Powered by **[AdScrape](https://www.adscrape.in/)**.

**Support:** open an issue on the Actor's Apify page or message us on the [Apify Discord](https://discord.com/invite/jyEM2PRvMU).

# Actor input Schema

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

List of keywords or brand names to look up in the Ads Transparency Center.

## `maxAdvertisersPerQuery` (type: `integer`):

Max advertiser (brand) suggestions to return per query. Legacy alias: maxSuggestionsPerQuery.

## `maxWebsitesPerQuery` (type: `integer`):

Max website (domain) suggestions to return per query.

## Actor input object example

```json
{
  "queries": [
    "nike",
    "adidas"
  ],
  "maxAdvertisersPerQuery": 10,
  "maxWebsitesPerQuery": 10
}
```

# Actor output Schema

## `suggestions` (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 = {
    "queries": [
        "nike",
        "adidas"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapeio/google-ads-transparency-suggest").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 = { "queries": [
        "nike",
        "adidas",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("scrapeio/google-ads-transparency-suggest").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 '{
  "queries": [
    "nike",
    "adidas"
  ]
}' |
apify call scrapeio/google-ads-transparency-suggest --silent --output-dataset

```

## MCP server setup

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

```

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/FS4AoUnqzQt8xbGJ6/builds/SnY6aWoUCCjehVBg6/openapi.json