# Google Ads Transparency Scraper (`unseenuser/google-ads`) Actor Export every public ad any brand is running on Google - by name, domain, or advertiser ID. - **URL**: https://apify.com/unseenuser/google-ads.md - **Developed by:** [Unseen User](https://apify.com/unseenuser) (community) - **Categories:** Automation, Lead generation, Social media - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing $10.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Google Ads Spy — Competitor Ad Scraper See every ad your competitors run on Google. Paste a mix of brand names, domains, or Google advertiser IDs — the actor auto-detects what each entry is, pulls every public ad from the **Google Ads Transparency Center**, and optionally enriches each one with headlines, descriptions, creative images, and impression stats. ### Input One required field, everything else optional: | Field | Type | Default | What it does | | --- | --- | --- | --- | | **Advertisers** | list of strings | — | One per line. Accepts brand names (`nike`), domains (`lululemon.com`), or advertiser IDs (`AR01614014350098432001`). Mixed entries work. | | Max ads per advertiser | integer | `100` | Cap per advertiser. `0` = unlimited. | | Include full ad details | boolean | `false` | When on, every ad also includes headlines, descriptions, creative variations, regions, and impression stats. | | Start date | date | — | Earliest `first_shown` date for returned ads. | | End date | date | — | Latest `last_shown` date for returned ads. | | Region | string | — | Two-letter region code (`US`, `GB`, `AU`, …). Worldwide when blank. | | Political ads only | boolean | `false` | Restrict to political ads. Region is required when enabled. | ### API key configuration (actor owner) The actor reads its ScrapeCreators key from the **`SCRAPECREATORS_API_KEY` environment variable** — end users never see or provide it. To set it on the Apify platform: 1. Open your actor on [Apify Console](https://console.apify.com/). 2. Go to **Source → Environment variables**. 3. Add a new variable: - Name: `SCRAPECREATORS_API_KEY` - Value: your key from [scrapecreators.com](https://scrapecreators.com) - **Tick "Secret"** so the value is encrypted and hidden. 4. Save and rebuild. The key is stored inside Apify's secret vault — it is **not** in the git repository. ### Example input ```json { "advertisers": ["nike", "lululemon.com", "AR01614014350098432001"], "maxAdsPerAdvertiser": 50, "includeAdDetails": true, "startDate": "2025-01-01", "endDate": "2025-11-10" } ```` ### Output Each row of the dataset is one ad. Columns are ordered for the Apify table view — readable identifiers first, ad copy next, dates and stats in the middle, technical IDs and full nested data at the end. | ## | Column | Type | Always present? | Notes | | --- | --- | --- | --- | --- | | 1 | `advertiserName` | string | yes | Brand the ad belongs to. | | 2 | `domain` | string | yes | Advertiser's website. | | 3 | `format` | string | yes | `text`, `image`, or `video`. | | 4 | `headline` | string | details only | Headline of the primary creative variation. | | 5 | `description` | string | details only | Description of the primary variation. | | 6 | `destinationUrl` | string | details only | Click-through URL. | | 7 | `adText` | string | details only | OCR'd full ad text (per ScrapeCreators). | | 8 | `imageUrl` | string | sometimes | Creative image when available. | | 9 | `firstShown` | ISO date | yes | First day the ad ran. | | 10 | `lastShown` | ISO date | yes | Last day the ad ran. | | 11 | `daysActive` | integer | yes | Computed from first/last shown. | | 12 | `regions` | string | details only | Comma-separated region names (`United States, Canada`). | | 13 | `impressionsMin` | number | details only | Lower bound from `overallImpressions`. | | 14 | `impressionsMax` | number | details only | Upper bound. | | 15 | `variationsCount` | integer | details only | Number of creative variations the ad ran. | | 16 | `adTransparencyUrl` | string | yes | Direct link to inspect the ad on Google Ads Transparency Center. | | 17 | `advertiserId` | string | yes | Google's `AR…` ID. | | 18 | `creativeId` | string | yes | Google's `CR…` ID. | | 19 | `scrapedFrom` | string | yes | What input produced this row, e.g. `"domain: lululemon.com"` or `"search \"nike\" (Nike Inc)"`. | | 20 | `variations` | array | details only | Full list of creative variations (each with headline/description/destinationUrl/imageUrl/allText). | | 21 | `creativeRegionsDetail` | array | details only | Raw `creativeRegions` array. | | 22 | `regionStats` | array | details only | Per-region first/last-shown and impression breakdown. | Columns marked **details only** are filled when **Include full ad details** is enabled, otherwise they are `null`. The column itself is still present so CSV exports stay consistent. #### Example row (with details) ```json { "advertiserName": "Foreplay Ventures Inc", "domain": "foreplay.co", "format": "video", "headline": "Work Pants, But Stretchy", "description": "Move In Lightweight, Comfortable Work Pants That Take Your Day In New Directions.", "destinationUrl": "shop.lululemon.com", "adText": "Sponsored Ω lululemon shop.lululemon.com ...", "imageUrl": "https://tpc.googlesyndication.com/archive/simgad/2201045439314643090", "firstShown": "2024-08-02T12:33:35.000Z", "lastShown": "2025-11-10T19:31:13.000Z", "daysActive": 465, "regions": "United States", "impressionsMin": null, "impressionsMax": null, "variationsCount": 2, "adTransparencyUrl": "https://adstransparency.google.com/advertiser/AR.../creative/CR...", "advertiserId": "AR09628680369637163009", "creativeId": "CR15036700036807262209", "scrapedFrom": "domain: foreplay.co", "variations": [ { "headline": "...", "description": "...", "destinationUrl": "...", "allText": "...", "imageUrl": "..." } ], "creativeRegionsDetail": [ { "regionCode": "US", "regionName": "United States" } ], "regionStats": [ { "regionCode": "US", "firstShown": null, "lastShown": "2025-06-18T05:00:00.000Z", "impressions": {}, "platformImpressions": [] } ] } ``` #### Run summary A summary object is written to the default key-value store under the `OUTPUT` key: ```json { "advertisersProcessed": 4, "adsScraped": 137, "adsFailed": 0, "errors": [], "creditsRemaining": 9926424, "finishedAt": "2025-11-10T19:31:13.000Z" } ``` ### Schemas This actor ships with the following Apify schema files so the Console can render results nicely: | Schema | File | Purpose | | --- | --- | --- | | **Output schema** (via `storages`) | [`.actor/actor.json`](./.actor/actor.json) | Links the dataset and key-value store schemas below into the actor definition. | | **Dataset schema** | [`.actor/dataset_schema.json`](./.actor/dataset_schema.json) | Defines two views for the dataset — `Overview` (human-readable key columns with image previews and links) and `Full detail` (every field). Labels, formats, and column order are all set here. | | **Key-value store schema** | [`.actor/key_value_store_schema.json`](./.actor/key_value_store_schema.json) | Describes the `OUTPUT` summary key so users know what to look for in the key-value store. | | **Live-view OpenAPI schema** | *not applicable* | This is a batch scraper — it does not run an HTTP server inside the actor, so no OpenAPI schema is provided. | ### Disclaimer > **Please read before using this Actor.** > > This Actor is an independent tool that retrieves publicly available advertising data from the Google Ads Transparency Center via the [ScrapeCreators](https://scrapecreators.com) API. It is intended for legitimate purposes including competitive research, marketing analysis, brand safety monitoring, academic research, journalism, and ad transparency verification. **Independence & trademarks.** This Actor is not affiliated with, endorsed by, sponsored by, or in any way officially connected to Google LLC, Alphabet Inc., Apify Technologies, ScrapeCreators, or any of the advertisers whose ads are returned. All product names, logos, brands, trademarks, and registered trademarks referenced by this Actor or its output are the property of their respective owners. Any use of these names is for identification purposes only and does not imply endorsement. **Data source & limitations.** All data returned originates from Google's own public [Ads Transparency Center](https://adstransparency.google.com/). This Actor cannot retrieve ads that require authentication, are age/geo-restricted, or have been marked private by the advertiser — these are limitations of Google's disclosure system, not of this tool. Creative copy (`headline`, `description`, `adText`) is extracted via OCR for image and video creatives by the upstream ScrapeCreators API and may contain minor inaccuracies. Fields, availability, and structure may change without notice if Google or ScrapeCreators modify their services. **Your responsibility.** You are solely responsible for ensuring your use of this Actor and any data it produces complies with: - [Google's Terms of Service](https://policies.google.com/terms) and the terms of the [Ads Transparency Center](https://adstransparency.google.com/). - [ScrapeCreators' Terms of Service](https://scrapecreators.com). - [Apify's Terms of Service and Acceptable Use Policy](https://apify.com/terms-of-use). - All applicable data-protection, intellectual-property, consumer-protection, advertising, anti-competition, and other laws in your jurisdiction — including but not limited to GDPR, UK GDPR, CCPA/CPRA, LGPD, the DMCA, and any applicable copyright or trademark statutes. By running this Actor you confirm that your intended use is lawful and that you hold any consents, licences, or authorisations required in your jurisdiction. **No personal data collection.** The Google Ads Transparency Center publishes advertiser business entities and creative content, not end-user personal data. Political ads may, however, reference public figures — treat any such content with appropriate editorial and legal care. **No warranty.** This Actor is provided **"as is"** and **"as available"**, without warranties of any kind, whether express or implied — including but not limited to implied warranties of merchantability, fitness for a particular purpose, accuracy, completeness, reliability, availability, or non-infringement. No guarantee is made that the Actor will return every ad an advertiser has ever run, or that returned data is current as of any particular moment. **Limitation of liability.** To the maximum extent permitted by applicable law, the Actor owner, contributors, Apify, and ScrapeCreators shall not be liable for any direct, indirect, incidental, special, consequential, exemplary, or punitive damages — including but not limited to loss of profits, revenue, data, goodwill, or business opportunities — arising out of or in connection with your use of, or inability to use, this Actor or the data it returns, even if advised of the possibility of such damages. In jurisdictions where limitation or exclusion of liability for consequential or incidental damages is not permitted, liability is limited to the fullest extent permitted by law. **Indemnification.** You agree to indemnify and hold harmless the Actor owner, contributors, Apify, and ScrapeCreators from any claims, damages, liabilities, losses, costs, or expenses (including reasonable legal fees) arising out of your use of this Actor, your violation of these terms, or your violation of any applicable law or third-party right. **Report concerns.** If you believe an ad has been returned in error, your trademarks are being misused in downstream output, or scraped data is being used in a way that violates these terms, contact the Actor owner through the Apify Console. ### Running locally ```bash npm install export SCRAPECREATORS_API_KEY=your-key mkdir -p storage/key_value_stores/default echo '{"advertisers":["lululemon.com"],"maxAdsPerAdvertiser":5}' \ > storage/key_value_stores/default/INPUT.json npm start ``` Scraped ads appear under `storage/datasets/default/`. ### Tests ```bash npm test ``` Runs the full suite (client unit tests, 10 actor end-to-end scenarios against a local mock ScrapeCreators server, and a retry/backoff test). ### Deploying ```bash npm install -g apify-cli apify login apify push ``` After the first push, set the `SCRAPECREATORS_API_KEY` secret in the actor's environment variables (see above) before running. # Actor input Schema ## `advertisers` (type: `array`): One per line. Accepts any of: • Brand name — e.g. nike • Website domain — e.g. lululemon.com • Google advertiser ID — e.g. AR01614014350098432001 ## `maxAdsPerAdvertiser` (type: `integer`): Cap the number of ads scraped per advertiser. Set to 0 for no limit. ## `includeAdDetails` (type: `boolean`): Fetch headlines, descriptions, creative variations, and region/impression stats for every ad. Uses slightly more credits. ## `startDate` (type: `string`): Only include ads first shown on or after this date. Leave blank for no lower bound. ## `endDate` (type: `string`): Only include ads last shown on or before this date. ## `region` (type: `string`): Two-letter region code (e.g. US, GB, AU). Leave blank for worldwide. ## `politicalOnly` (type: `boolean`): Restrict to political ads (region required when enabled). ## Actor input object example ```json { "advertisers": [ "lululemon.com" ], "maxAdsPerAdvertiser": 100, "includeAdDetails": false, "politicalOnly": false } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "advertisers": [ "lululemon.com" ] }; // Run the Actor and wait for it to finish const run = await client.actor("unseenuser/google-ads").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "advertisers": ["lululemon.com"] } # Run the Actor and wait for it to finish run = client.actor("unseenuser/google-ads").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "advertisers": [ "lululemon.com" ] }' | apify call unseenuser/google-ads --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=unseenuser/google-ads", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper", "description": "Export every public ad any brand is running on Google - by name, domain, or advertiser ID.", "version": "0.0", "x-build-id": "dfCejXsWthVECRWlR" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/unseenuser~google-ads/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-unseenuser-google-ads", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/unseenuser~google-ads/runs": { "post": { "operationId": "runs-sync-unseenuser-google-ads", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/unseenuser~google-ads/run-sync": { "post": { "operationId": "run-sync-unseenuser-google-ads", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "advertisers" ], "properties": { "advertisers": { "title": "Advertisers", "minItems": 1, "type": "array", "description": "One per line. Accepts any of:\n• Brand name — e.g. nike\n• Website domain — e.g. lululemon.com\n• Google advertiser ID — e.g. AR01614014350098432001", "items": { "type": "string" } }, "maxAdsPerAdvertiser": { "title": "Max ads per advertiser", "minimum": 0, "type": "integer", "description": "Cap the number of ads scraped per advertiser. Set to 0 for no limit.", "default": 100 }, "includeAdDetails": { "title": "Include full ad details", "type": "boolean", "description": "Fetch headlines, descriptions, creative variations, and region/impression stats for every ad. Uses slightly more credits.", "default": false }, "startDate": { "title": "Start date", "type": "string", "description": "Only include ads first shown on or after this date. Leave blank for no lower bound." }, "endDate": { "title": "End date", "type": "string", "description": "Only include ads last shown on or before this date." }, "region": { "title": "Region", "type": "string", "description": "Two-letter region code (e.g. US, GB, AU). Leave blank for worldwide." }, "politicalOnly": { "title": "Political ads only", "type": "boolean", "description": "Restrict to political ads (region required when enabled).", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```