google-ads-transparency
Skill0 starsChanged 3 months agoMITView on GitHub
Look up any advertiser's live and historical Google ads via the Google Ads Transparency Center — creatives, formats, flight dates, surfaces (Search, YouTube, Display, Shopping, Maps, Play) and per-country reach. Use for competitor ad research, checking whether a domain runs Google Ads, auditing a client's own visible ads, trademark or brand-abuse checks, and pulling creative inspiration. Triggers on "ads transparency", "Google Ads Transparency Center", "what ads is X running", "competitor Google ads", "is this domain running ads", "ad library" (Google), or a request to check an advertiser's ad history.
In this repository5 other files it gives its agents.
- fish-audio-ttsSkill
- geo-query-miningSkill
- human-writing-filterSkill
- sa-compliance-officerSkill
- tidy-downloadsSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Do not present Transparency Center output as a spend or performance estimate.
- Very specific: line 73
When throttled, the endpoint does not error.
- Very specific: line 96
Run from the skill directory.
- Very specific: line 129
Add --json out.json or --csv out.csv to save.
- Very specific: line 139
Default --delay is 2s. For runs over ~20 calls use --delay 4 or higher.
- Very specific: line 166
Every result includes a url field linking to the ad's page on the Transparency Centre.
- Distinctive: line 176
Write outputs to your chosen project folder, not to a working directory.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Google Ads Transparency Center
Public archive of every ad served on Google Search, YouTube, Display, Shopping, Maps and Play. No account, no API key, no client access needed — this works on any advertiser, including competitors.
What you can and cannot get
| Available | Not available |
| Every archived creative (text, image, video) | Spend — except for political ads in supported regions |
| First shown / last shown / days running | Impressions, other than bucketed lower bounds per country |
| Surface breakdown (Search, YouTube, Shopping, Maps, Play) | Landing page / click destination URLs |
| Per-country flight dates | Keywords, bids, targeting, budgets |
| Advertiser legal name, home country, verification status | Anything about ads that never ran |
Do not present Transparency Center output as a spend or performance estimate. It shows what ran and where, not how well it did or what it cost.
Three routes — try them in this order
1. Browser (default, free, most reliable). scripts/browser_client.js runs the RPC
calls inside a tab that is already on adstransparency.google.com, so they carry the
page's own session. This is the route that keeps working under load.
2. Python CLI (free, convenient for files). scripts/ads_transparency.py makes the
same calls from the shell and writes JSON/CSV directly. Google rate-limits scripted
clients hard and eventually answers with a reCAPTCHA — never attempt to solve that
challenge. Once challenged, the client stays challenged for a long while; switch routes.
3. Apify (paid, reliable at volume). For hundreds of creatives, or when the other two
are blocked. Verified actor: s-r/google-ads-transparency (about 1 US cent per run plus
0.1 US cents per result).
Browser usage
Open the site, then read scripts/browser_client.js and pass its contents plus an
await expression into evaluate_script (chrome-devtools) or javascript_tool
(Browser pane):
preview_start url="https://adstransparency.google.com/?region=ZA"// after the ATC module definition:
await ATC.advertisers('nike', 2710)
await ATC.ads({ advertiserId: 'AR13621983456417284097', region: 2710, limit: 200 })
await ATC.ads({ domain: 'competitor.co.za', region: 2710, format: 3 })
await ATC.creative('AR136…', 'CR011…', 2710)
await ATC.profile('AR136…')
// detail for many creatives — use this, never your own loop:
const list = await ATC.ads({ advertiserId: ID, region: 2710, limit: 200 })
const { results, failed } = await ATC.creativesBulk(ID, list.map(a => a.creativeId), 2710)Return a JSON.stringify(...) of the result — evaluate_script truncates large objects,
so slice or project fields when pulling hundreds of ads. ATC.ads paginates internally.
Country results come back as numeric region codes; map them with
references/regions.json.
To get a CSV out, build it in the page and trigger a blob download, then move the file
from ~/Downloads — far easier than round-tripping a large string through the tool.
The silent-empty failure — the one that will bite you
When throttled, the endpoint does not error. It returns HTTP 200 with valid JSON
and no payload field. A naive data['1'] || {} turns that into an empty result, which
reads downstream as "this advertiser has no ads" — wrong data presented as fact.
Observed on a real 93-creative pull: an unthrottled loop silently lost detail for 31 of
93 creatives. The same pull through ATC.creativesBulk at the default 350 ms got 93 of
93, needing 19 retries across 115 calls. The failures are frequent, not exotic.
The hardened client handles this for you:
ATC.call()validates that the expected payload field is present and retries with exponential backoff, throwing only afterATC.config.retriesattempts.ATC.creativesBulk()paces the calls and returns{results, failed, stats}. Always checkfailedbefore reporting — anything in it is missing data, not absent data.- A CAPTCHA body throws immediately without burning retries.
Rules: never call fetch against these endpoints directly, bypassing ATC.call(). Never
treat an empty response as an empty result. If stats.retries is climbing or calls start
throwing, raise ATC.config.delayMs (350 → 750) rather than pushing through.
Python usage
Run from the skill directory. --region takes an ISO alpha-2 code (default ZA), or
ALL for anywhere.
Resolve an advertiser name to an ID:
python scripts/ads_transparency.py advertisers "nike" --region USList a domain's ads:
python scripts/ads_transparency.py ads --domain competitor.co.za --region ZA --limit 100List one advertiser's ads, filtered:
python scripts/ads_transparency.py ads --advertiser AR18378488041124659201 --format video --platform youtubeFull detail for one creative — the only way to get per-country dates and surfaces:
python scripts/ads_transparency.py creative AR18378488041124659201 CR08612997106090639361 --region ZAAdvertiser profile:
python scripts/ads_transparency.py profile AR18378488041124659201Add --json out.json or --csv out.csv to save. Both can be combined; without either,
results print to stdout.
Rate limiting — read this before a bulk pull
The endpoint tolerates roughly a dozen quick calls from a scripted client before it
starts serving CAPTCHAs. Once challenged it stays challenged for a long while, and
retrying does not help — the script raises ChallengeError and you should switch to the
browser or Apify route.
- Default
--delayis 2s. For runs over ~20 calls use--delay 4or higher. adscosts one call per 40 creatives.creativecosts one call each — a 100-creative detail pull is 100 calls, so use the browser route or Apify for that.- Pull the creative list first, filter down to the ads that matter, then fetch detail only for those.
- The silent-empty-200 failure described under the browser route applies here too.
rpc()validates the payload field and retries; a run that ends in200 OK but no field '1'means throttling, so raise--delay. Never edit that check away to make a run finish.
Apify route
call-actor actor="s-r/google-ads-transparency"
input={"domain": "competitor.co.za", "region": "ZA", "ads_count": 100}
get-dataset-items datasetId=<from the run result>Input also accepts advertiser_id, creative_id, search, format, start_date,
end_date, detail (per-country breakdown) and political. Set maxTotalChargeUsd in
callOptions to cap spend. Tell the user roughly what a large run will cost before
launching it.
Working the results
- Creative preview URLs point at
displayads-formats.googleusercontent.com; image ads also carry archived<img>HTML. Both render in a browser — use the Browser pane to view creatives rather than trying to parse ad copy out of them. - Every result includes a
urlfield linking to the ad's page on the Transparency Centre. Use these when citing findings so the user can verify. days_runningpluslast_shownis the best available proxy for what a competitor is committed to: long-running creatives are the ones that are working for them.- Cross-check the advertiser ID before reporting. Domain search can surface resellers, affiliates and franchisees advertising the same domain — the Nike domain, for example, returns several unrelated advertiser entities. Report which legal entity ran what.
Saving output
Write outputs to your chosen project folder, not to a working directory. For competitor research, write both the raw JSON/CSV and a short markdown summary of what the competitor is running and since when.
Reference
references/rpc-api.md documents the endpoints, request/response field numbers, enums,
and how to re-capture them if Google changes the API. references/regions.json maps ISO
alpha-2 codes to Google region codes.
These are undocumented internal endpoints. If a route starts returning empty results or
unexpected shapes, Google has probably changed something — re-capture the request bodies
per references/rpc-api.md before assuming the data is genuinely absent.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

