Google Ads Transparency Competitor Intelligence

Scrape the Google Ads Transparency Center and turn competitor advertising into a searchable intelligence feed. Use it for competitor ad research, creative discovery, landing-page monitoring, active campaign tracking and ad change detection.

Turns Google Ads Transparency Center listings into structured competitor intelligence: normalized ad creatives, activity flags, creative clusters, per-advertiser summaries, and change events between runs.

Input

Field	Type	Default	Notes
advertisers	string[]	— (required)	Per competitor: a domain (nike.com), a name (Nike), or a Transparency Center advertiser ID (AR…). URLs are accepted and reduced to a domain.
region	string	"anywhere"	anywhere or a two-letter ISO country code.
maxAdsPerAdvertiser	integer	200	Creative cap per advertiser.
maxPages	integer	10	Result-page cap (see limitations).
requestTimeoutSecs	integer	30	Per-request timeout.
concurrency	integer	2	Advertisers processed in parallel.
minRequestDelayMs	integer	800	Client-side rate limit between requests / retries.
maxRetries	integer	2	Retries for transient failures (timeout, network-error, http-error). Safety failures are never retried.
maxResponseBytes	integer	4000000	Byte ceiling per response.
longRunningDays	integer	30	Run-duration threshold for the long-running flag.
newAdWindowDays	integer	7	First-shown recency for the new flag.
activeWindowDays	integer	14	Last-shown recency for the active flag.
resetSnapshot	boolean	false	Ignore the stored snapshot; fresh baseline.

Output

Three item types (see .actor/dataset_schema.json):

• type: "ad" — normalized creative (format, adCopy, landingPageUrl / landingPageDomain, regions, firstShownAt, lastShownAt, variantCount) plus derived runDurationDays, isActive, isNew, isLongRunning, and a deterministic creativeClusterId (format + landing domain + first 8 normalized copy tokens, FNV-hashed).
• type: "change" — new_ad, stopped_ad, resumed_ad, copy_changed vs. the stored snapshot. The first observation of an advertiser is a baseline (no events). Events are fully sorted for reproducibility.
• type: "advertiser_summary" — totalAds, activeAds, newAds, longRunningAds, formatBreakdown, topLandingDomains, creativeClusters, first/last shown, a deterministic activityScore (0–100), and partial / error when the run for that advertiser was incomplete.

A SUMMARY record with per-advertiser reports, totals, changeCounts and failuresByReason is written to the key-value store.

Resilience

• Broken or incomplete ad objects are counted (malformedAds) and skipped — they never stop the run.
• Transient request failures are retried up to maxRetries with the configured delay; each retry is recorded.
• If every attempt fails, the advertiser's stored snapshot is left untouched and its summary is marked partial with an error — no false "all ads stopped".
• One failing advertiser never affects the others.
• No Google account, no CAPTCHA solving, no private endpoints. All fetches go through the shared safeFetch (SSRF-guarded, redirect-capped, byte-limited, timeout cleared in finally).

Known limitations

• The Transparency Center is a JavaScript application backed by an internal RPC that expects POST with signed tokens. This Actor issues a GET against the public advertiser / search page and parses framed JSON or an embedded state blob. When Google returns an interstitial or an unrecognised layout the parser yields zero ads and a warning, never a crash. maxPages is honoured by the interface but the GET path is effectively single-page; supply advertiser IDs and/or run behind an unblocker for depth. All normalization, clustering, scoring, diffing and resilience logic is fully implemented and fixture-tested.
• regions, firstShownAt / lastShownAt, format and variantCount are only populated when the payload exposes them.

Commands

npm ci                                                          # monorepo root
npm run check -w google-ads-transparency-competitor-intelligence
npm run smoke -w google-ads-transparency-competitor-intelligence  # offline
npx apify validate-schema

Deployment

Not deployed here. apify push is intentionally not run — the lead engineer handles deployment.