Use Google Ads Advertiser Creative History Scraper with Python

Look up an advertiser's ad history on the Google Ads Transparency Center by URL, name, or domain, with ad format, preview media, and first/last shown dates per creative.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

{
  "advertiserUrl": "https://adstransparency.google.com/advertiser/AR16735076323512287233",
  "includeDetails": true,
  "maxAdsPerAdvertiser": 1,
  "maxItems": 1,
  "mode": "advertiser",
  "political": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "region": "anywhere",
  "startUrls": []
}

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`mode`	string	required	Which kind of lookup to run.
`advertiserUrl`	string	optional	Advertiser or creative URL from adstransparency.google.com (mode=advertiser or creative).
`advertiserId`	string	optional	Google advertiser ID starting with AR (mode=advertiser or creative).
`domain`	string	optional	Domain to search across every advertiser Google links to it (mode=domain), e.g. nike.com.
`searchQuery`	string	optional	Brand name or keyword resolved through Google's advertiser suggestions (mode=search).
`startUrls`	array	optional	Additional advertiser or creative URLs (mode=advertiser or creative), as {url} request-list objects.
`creativeId`	string	optional	Google creative ID starting with CR (mode=creative). Also provide advertiserId or advertiserUrl.
`region`	string	optional	Only return ads shown in this country. 'anywhere' applies no region filter. Required when political is enabled.
`format`	string	optional	Restrict to one creative format. Leave empty for all formats.
`platform`	string	optional	Restrict to one Google surface. Leave empty for all platforms.
`political`	boolean	optional	Return only political or issue ads. Google requires a country region for this filter.
`startDate`	string	optional	Client-side date filter applied to the fetched slice. Leave empty for no lower bound.
`endDate`	string	optional	Client-side date filter applied to the fetched slice. Leave empty for no upper bound.
`maxAdsPerAdvertiser`	integer	optional	Per-advertiser cap (1-1000). The run also stops at maxItems.
`maxItems`	integer	optional	Total ads to emit across all targets (1-1000).
`includeDetails`	boolean	optional	Fetch per-creative detail and preview content for copy, media and region stats. Disable for a faster list-only run.
`proxyConfiguration`	object	optional	Optional proxy override. The actor uses an Apify automatic proxy by default.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/9wEoeBWrpFtgDeTGz/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

Per-advertiser Google Ads Transparency Center creatives with ad format, preview media, and first/last shown dates.

Questions before you run

Which inputs are required?

The published required fields are mode

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build prhya8gN9RuRfH4g7 and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.