agentleFS
MDizzleZAMDizzleZA/claude-skills/google-ads-transparency/SKILL.md

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.

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
  1. Distinctive:

    Do not present Transparency Center output as a spend or performance estimate.

    line 22
  2. Very specific:

    When throttled, the endpoint does not error.

    line 73
  3. Very specific:

    Run from the skill directory.

    line 96
  4. Very specific:

    Add --json out.json or --csv out.csv to save.

    line 129
  5. Very specific:

    Default --delay is 2s. For runs over ~20 calls use --delay 4 or higher.

    line 139
  6. Very specific:

    Every result includes a url field linking to the ad's page on the Transparency Centre.

    line 166
  7. Distinctive:

    Write outputs to your chosen project folder, not to a working directory.

    line 176

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

AvailableNot available
Every archived creative (text, image, video)Spend — except for political ads in supported regions
First shown / last shown / days runningImpressions, other than bucketed lower bounds per country
Surface breakdown (Search, YouTube, Shopping, Maps, Play)Landing page / click destination URLs
Per-country flight datesKeywords, bids, targeting, budgets
Advertiser legal name, home country, verification statusAnything 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 after ATC.config.retries attempts.
  • ATC.creativesBulk() paces the calls and returns {results, failed, stats}. Always check failed before 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 US

List a domain's ads:

python scripts/ads_transparency.py ads --domain competitor.co.za --region ZA --limit 100

List one advertiser's ads, filtered:

python scripts/ads_transparency.py ads --advertiser AR18378488041124659201 --format video --platform youtube

Full detail for one creative — the only way to get per-country dates and surfaces:

python scripts/ads_transparency.py creative AR18378488041124659201 CR08612997106090639361 --region ZA

Advertiser profile:

python scripts/ads_transparency.py profile AR18378488041124659201

Add --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 --delay is 2s. For runs over ~20 calls use --delay 4 or higher.
  • ads costs one call per 40 creatives. creative costs 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 in 200 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 url field linking to the ad's page on the Transparency Centre. Use these when citing findings so the user can verify.
  • days_running plus last_shown is 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.