google-ads-transparency

Competitor ads from the Google Ads Transparency Center in Python: every ad a domain, advertiser or brand is running, the ad copy (also read off the picture of text ads with OCR), landing URLs and UTM tags where Google publishes them, and a new / stopped / long-running report for any period.

This package is a thin client for the Apify Actor Google Ads Transparency Report. The Actor does the scraping, proxies and retries on Apify's servers; this package starts it and hands you the tables as Python lists of dicts.

pip install google-ads-transparency

Quick start

You need an Apify API token: sign up at apify.com, then copy the token from Console > Settings > Integrations.

export APIFY_TOKEN=apify_api_...

from google_ads_transparency import Client

result = Client().run(domains=["hubspot.com"], country="US", details=True, ocr=True, max_details=20)

print(result.status, len(result.ads))
for ad in result.ads[:5]:
    print(ad["format"], ad["last_shown"], ad["headline"], ad["destination_url"])

A run takes from a few seconds (the ad list only) to minutes (ad text for hundreds of ads).

What you get back

Client.run() returns a Result:

Plus status, status_message, ok, run_id, console_url and charged_events.

An empty ads list is not always "no ads". Check result.ok and result.targets: a target Google refused is failed, one the run did not reach (cost or time limit) is skipped, and only empty means the Transparency Center answered and has nothing.

Arguments

Unset arguments use the Actor's defaults. Bad values raise ConfigError before anything is started or paid for.

Weekly competitor report

result = Client().run(domains=["hubspot.com", "salesforce.com", "zoho.com"], report_days=7)
for row in result.report:
    print(row)

Run it on a schedule (cron, Airflow, n8n) every 7 days: the Actor reads only the recent part of each list, so a weekly run stays cheap even for a large advertiser.

Cost

You pay Apify per event, only for what the run returns. Prices on the free plan (lower on paid plans):

Current prices on all plans are on the Actor page. Use max_ads, max_details and max_total_charge_usd to stay within budget.

Migrating from Google-Ads-Transparency-Scraper

That package has not been updated since July 2023. The same tasks with this one:

The difference in shape: the old package made one request per ad; here one run() returns all ads of all your targets at once, with statuses for each target.

Limitations

These come from what Google publishes:

• Most text ads are archived only as a picture; with ocr=True their text is read from it (text_source == "ocr").
• Text ads carry no landing URL at all; video ads mostly do, image ads rarely.
• The Transparency Center searches by advertiser or domain only, not by keyword.
• One country per run.

License

MIT. This package is not affiliated with Google.