Google Ads Transparency
# Google Ads Transparency Scraper (Python)
A small Python script that lists the ads any domain runs, taken from the **Google Ads Transparency Center** (Google's ad library). No API key, no login, no dependencies beyond the standard library.
For each ad you get the advertiser, format, **first shown, last shown and days shown**, plus a link to the ad in the Transparency Center. Filter by country and format, keep only long-running ads, export JSON or CSV.
```bash
python gads_transparency.py nike.com --region US --format text --min-days 30 --sort longest
```
Also works as an **MCP server** for Claude, Cursor and other AI clients: a free `list_ads` tool, plus `get_ads_with_copy` for ad text through the hosted version. See [Use it as an MCP server](#use-it-as-an-mcp-server).
## Is there a Google Ads Transparency API?
No. Google does not offer an official API for the Ads Transparency Center. The website loads its data from an internal JSON endpoint, and this script calls that same endpoint the way the site does:
```
POST https://adstransparency.google.com/anji/_/rpc/SearchService/SearchCreatives
```
The request is a form field `f.req` holding a small JSON object: the domain, optional country and format filters, a page size of 40 and a page token for the next page. `gads_transparency.py` is about 150 lines and you can read all of it in a few minutes.
## Quick start
Requires Python 3.8+. Nothing to install for the script (the MCP server needs `pip install -r requirements.txt`).
```bash
git clone https://github.com/datalumehq/google-ads-transparency-scraper.git
cd google-ads-transparency-scraper
python gads_transparency.py nike.com
```
Or download `gads_transparency.py` on its own and run it.
## Options
| Option | What it does | Example |
|---|---|---|
| `domain` | Advertiser website (required) | `nike.com` |
| `--region` | Country where the ad was shown: a 2-letter code from the built-in list, or a numeric region ID | `--region US` |
| `--format` | `text`, `image` or `video` | `--format text` |
| `--max` | Maximum ads to fetch (default 100) | `--max 400` |
| `--min-days` | Keep ads shown on at least N days | `--min-days 30` |
| `--sort` | `recent` (default) or `longest` | `--sort longest` |
| `--csv FILE` | Write CSV instead of printing JSON | `--csv ads.csv` |
Region IDs are `2000 + ISO 3166-1 numeric country code` (United States is 840, so 2840). Pass any numeric ID if your country is not in the built-in list.
## Output
Real output from 17 November 2026 (`nike.com`, US, text ads; Google reported 7,000 to 8,000 ads for this filter):
```json
[
{
"advertiserId": "AR16735076323512287233",
"advertiserName": "Nike, Inc.",
"domain": "nike.com",
"creativeId": "CR18169758746572488705",
"format": "text",
"firstShown": "2022-11-30",
"lastShown": "2026-11-17",
"daysShown": 1401,
"transparencyUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR18169758746572488705?region=anywhere"
}
]
```
`daysShown` is the number of days Google recorded the ad as shown. An ad that an advertiser keeps paying for over hundreds of days is usually one that works, which is why `--min-days 30 --sort longest` is a quick way to find a competitor's proven ads.
## Why there is no ad copy here
The list endpoint returns dates and IDs, not the headline and description. Getting the copy takes one more request per ad, and then a second problem appears: for many large advertisers Google stores text ads **only as images**. In our tests, 149 of 150 booking.com and 120 of 120 expedia.com text ads had no text version at all, so the copy has to be read from the screenshot.
That part (per-ad detail requests, screenshot reading, countries per ad, retries when Google rate-limits) is what the hosted version below does. This script stays small on purpose.
## Limits of this script
- One domain per run, list data only (no ad copy, no per-country breakdown, no impression ranges).
- No proxy handling. If you request many pages quickly, Google answers with a non-JSON page; the script stops and tells you. Wait a few minutes and use a smaller `--max`.
- `--min-days` and `--sort` apply to the ads that were fetched, so raise `--max` to look deeper.
- The endpoint is internal and can change without notice. If the script breaks, please open an issue.
## Hosted version with ad copy
If you need the copy, many domains, or a daily feed of new ads, the same data source is available as a maintained Apify Actor: **[Google Ads Transparency Scraper - Ad Copy & Days Running](https://apify.com/datalume/google-ads-transparency-scraper)**.
It adds:
- **Ad copy** (headline, description, display URL), including screenshot-only text ads and responsive search ads
- **Countries per ad** with last shown date per country, and impression ranges where Google publishes them
- Search by **domain, advertiser ID or advertiser name**, many targets in one run
- Platform filter (Search, YouTube, Shopping, Maps, Play) and date range
- **Only new ads since the last run**, for scheduled monitoring
- Pay per result; failed rows are not charged
From Python (`pip install apify-client`, see `run_apify_actor.py`):
```python
from apify_client import ApifyClient
client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("datalume/google-ads-transparency-scraper").call(run_input={
"domains": ["booking.com"],
"region": "US",
"minDaysRunning": 30,
"sortBy": "longestRunning",
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item["daysShown"], item.get("headline"), item.get("description"))
```
The same features are available to AI agents through the MCP server below (`get_ads_with_copy`).
## Use it as an MCP server
`mcp_server.py` exposes two tools to any MCP client (Claude Desktop, Claude Code, Cursor, VS Code). Requires Python 3.10+.
| Tool | Cost | What it returns |
|---|---|---|
| `list_ads` | Free, no API key | One domain's ads: advertiser, format, first/last shown, days shown, link. Filters: country, format, minimum days shown, sort |
| `get_ads_with_copy` | Paid per result through your Apify account (about $0.002 per ad, $0.0035 per ad with copy on Apify's free plan) | Ad copy (headline, description, display URL) including screenshot-only text ads, countries per ad, many domains or advertiser names. Each call has a spending cap (`max_total_charge_usd`, default $0.25) |
Install:
```bash
git clone https://github.com/datalumehq/google-ads-transparency-scraper.git
cd google-ads-transparency-scraper
pip install -r requirements.txt
```
Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`) and most other clients use the same block. Use the full path to `mcp_server.py`:
```json
{
"mcpServers": {
"google-ads-transparency": {
"command": "python",
"args": ["/path/to/google-ads-transparency-scraper/mcp_server.py"],
"env": { "APIFY_TOKEN": "<optional, only for get_ads_with_copy>" }
}
}
}
```
Claude Code:
```bash
claude mcp add google-ads-transparency -- python /path/to/google-ads-transparency-scraper/mcp_server.py
```
Then ask in plain language, for example:
- "Which text ads has nike.com been running for 30+ days in the US?" (free)
- "Show me the headlines of booking.com's longest-running search ads in the US" (uses `get_ads_with_copy`)
Without `APIFY_TOKEN` the free tool works and the paid tool returns a message explaining how to add a token. Get a token at [console.apify.com/settings/integrations](https://console.apify.com/settings/integrations).
Prefer not to run anything locally? Apify's hosted MCP endpoint serves the same Actor: `https://mcp.apify.com?tools=datalume/google-ads-transparency-scraper` (sign in with Apify on first use).
## FAQ
**Is scraping the Google Ads Transparency Center allowed?**
The Transparency Center is a public site that Google built so anyone can see who is advertising. This script reads the same public data your browser does, without logging in. Use it responsibly: keep request volume low and check the terms that apply to you.
**Can I search by advertiser name instead of domain?**
Not in this script. The hosted version accepts advertiser names, advertiser IDs and Transparency Center links.
**Why do I get fewer ads than the website's counter shows?**
Google reports a rough range (for example 7,000 to 8,000), and this script stops at `--max`. Raise it to fetch more pages.
**Does it work for Google Ad Library, YouTube ads or Shopping ads?**
"Google Ad Library" is another name people use for the Ads Transparency Center. The list includes ads from Search, YouTube, Shopping, Maps and Play; this script does not filter by platform, the hosted version does.
## More
- Tutorial: [How to Export Google Ads Transparency Center Data (with Ad Copy) in Python](https://dev.to/datalume/how-to-export-google-ads-transparency-center-data-with-ad-copy-in-python-2h4a)
- Other scrapers by datalume: [apify.com/datalume](https://apify.com/datalume)
## License
MIT. Built with AI assistance; numbers come from real runs on the dates shown. MCP tools tested on 18 November 2026.
*Not affiliated with, endorsed by or sponsored by Google. This project only reads publicly available ad information from the Google Ads Transparency Center.*
TDQS
Scored across 2 tools
The two tools overlap in that both retrieve Google ads, but the split is clear: list_ads is free metadata-only, while get_ads_with_copy is paid and adds ad copy plus country coverage. Descriptions explicitly guide selection, though an agent might still initially hesitate over which to use when ad text is not the primary need.
Both names use snake_case with a clear verb_noun structure: list_ads and get_ads_with_copy. The get_ads_with_copy variant is more descriptive but remains predictable and consistent with the list/get action pattern.
The server has a narrow purpose, so two tools is defensible: one free listing tool and one paid copy-enrichment tool. It is slightly thin, but each tool has a distinct role and there is no redundant clutter.
The surface covers the main lifecycle of finding ads and retrieving their copy, including filtering by domain, region, format, duration, and spending caps. Minor gaps exist, such as richer advertiser lookup in the free tool or direct ad-detail retrieval, but core workflows are covered.