# Google Ads Scraper (`lurkapi/google-ads-scraper`) Actor Scrape Google Ads Transparency Center by advertiser ID, domain (auto-resolved), or search term. Optional OCR, landing-page scrape, media download. - **URL**: https://apify.com/lurkapi/google-ads-scraper.md - **Developed by:** [LurkAPI](https://apify.com/lurkapi) (community) - **Categories:** Automation, E-commerce, Lead generation - **Stats:** 3 total users, 1 monthly users, 90.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $1.20 / 1,000 ad scrapeds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 Scraper Spy on every ad your competitors are running on Google. Search, YouTube, Shopping, Maps, Play: text, image, and video, with run dates, click-through URLs, preview thumbnails, and full spend and impression disclosure for political ads. Pay only for what you get. ### 🎯 What you get Type a brand name, a website, or an advertiser ID. Press Start. You get back every ad that company is running right now, with: - **The ad itself**: headline, description, image or video, and a preview you can view in your browser - **When it ran**: the first day it appeared, the last day it was seen, and roughly how long it has been live - **Where it ran**: every country the ad showed in, with the last date it was seen there - **Where it points**: the click-through link and the display URL shown under the ad - **Every variation**: if the advertiser ran ten tweaks of the same creative, you get all ten - **Full political disclosure**: spend ranges, impression ranges, targeting locations, and FEC committee codes for US political advertisers Works for Shopify stores, your local plumber, and everyone in between. ### 📋 How to use it #### Step 1. Tell it who to scrape You have four ways to point the tool at an advertiser. Use any of them, or mix them in the same run: - **Type a website**: enter `shopify.com` and the tool finds the advertiser automatically - **Type a brand name**: enter `Shopify` and the tool returns a list of matching advertisers - **Paste an advertiser ID**: something like `AR01625195283841286145`. Open any advertiser page on [adstransparency.google.com](https://adstransparency.google.com) and look at the URL in your browser. The ID is the `AR...` code at the end. For example, in `https://adstransparency.google.com/advertiser/AR01625195283841286145`, the ID is `AR01625195283841286145`. - **Paste a Transparency Center link**: copy any URL from `adstransparency.google.com/advertiser/...` and paste it in #### Step 2. Narrow it down (optional) - **Country**: restrict to one country (`US`, `GB`, `DE`, `FR`, `JP`, etc.) or leave it global - **Platform**: choose between Search, YouTube, Shopping, Maps, Play, or any - **Date range**: only ads that were active between two dates - **Political only**: return only regulated political ads (requires a specific country) - **Format**: keep text ads, image ads, video ads, or any combination - **Already seen**: paste the ad IDs you have from previous runs and the tool skips them. You pay nothing for duplicates. See the next section. #### 🔁 Pay only for new ads Running a weekly or monthly tracking scrape on the same advertiser? Paste the ad IDs you already have into the **Already seen** input and the tool skips them completely. **How to get the IDs from a previous run**: open your previous run's Output tab on Apify, export the dataset as CSV, and paste the `creativeId` column straight into this field. #### Step 3. Pick your fields and add-ons Every core field is on by default. Turn off the ones you do not need to keep your rows lean. Below the field toggles, five optional add-ons let you pull in data that nobody else gives you: - **Read the text inside the image**. Most text ads on Google come back as flat images with no structured headline or description. Turn this on and the tool extracts the full ad copy from the picture itself. Works in 30+ languages automatically, no setup. Essential if you're studying competitor messaging or want a searchable database of ad copy. - **Download the actual ad image**. Save every ad creative as a PNG in your Apify storage. Perfect for building a swipe file, running visual diffs against past runs, or feeding a design team fresh reference material. - **Save the landing page**. Download the full HTML of the page each ad links to and stash it in your Apify storage. You only pay once per unique page. You get a permanent, searchable archive of every landing page your competitors are driving traffic to, perfect for auditing their funnel, spotting A/B tests, or comparing offers side by side. - **Per-country breakdown**. Know exactly which countries an ad ran in and when it was last seen in each one. For political ads, also get the impression band per country. Critical for international research, regulatory work, and global campaign audits. - **Decode political targeting**. Google publishes targeting location codes in a cryptic format. Turn this on and they come back as readable ZIP codes, states, and cities. Journalism gold for anyone covering political advertising. All add-ons are priced per ad, charged only when they actually produce a result. Leave them off for cheap basic scraping, turn them on when you need the depth. #### Step 4. Run it and export Click Start. Results fill the Output tab as each page is processed, so you can start downloading before the run even finishes. Every row has a `status` field. `Success` means the ad came through cleanly. Anything else is a plain English message telling you what happened and what to do next. ### 💰 Pricing You only pay for what you actually get. No subscriptions, no minimums. #### Always charged | Event | Price | When it fires | |---|---|---| | Ad found | $0.0015 | For each ad you receive | | Website or brand lookup | $0.001 | One-time fee per website or brand name you enter. Fires when we match it to the right advertiser in Google's database. Skip this fee entirely by pasting the advertiser ID directly. | #### Optional add-ons Turn these on one by one in the input form. You only pay when they actually produce data. | Add-on | Price | What it gives you | |---|---|---| | Region enrichment | $0.001 per ad | A breakdown of every country the ad ran in, with dates and (for political ads) impression bands | | Download the image | $0.002 per ad | Saves the ad image as a file in your Apify storage | | Read the text inside the image | $0.003 per ad | Works in English, Spanish, Chinese, Portuguese, French, German, Japanese, Arabic, Russian, Hindi, Italian, Korean, and 15+ more. The tool detects the language of each image on its own, no setup | | Save the landing page | $0.02 per unique page | Downloads the full HTML of the page each ad links to and saves it to your Apify storage. One download per unique URL: if 50 ads point to the same page, you pay once. | | Decode targeting locations | $0.002 per ad | For political ads, turns Google's location codes into readable ZIP codes, states, and countries | **Real example**: 500 ads from one advertiser with default settings costs around **$0.75**. Add OCR to all 500 and landing page saves (typically 20-50 unique pages per advertiser) and you add roughly **$2.00-$2.50**, charged only on successful downloads. ### 🏛️ Political ads Scrape any political advertiser and every row automatically includes: - Whether the ad was classified as political - The countries where it ran - The number of impressions it received, as a range - How much was spent, as a range, with the currency - The advertiser's legal name (as disclosed to regulators) - The advertiser's FEC committee code (for US political ads, cross-reference with FEC.gov) The spend and impression numbers only show up when you turn on the "political only" filter and pick a specific country. Want to see which ZIP codes a campaign targeted? Turn on the **Targeting locations** add-on. Great for journalism, compliance, and opposition research, without writing a line of code. ### 🔒 Ads for age-restricted categories (alcohol, gambling, pharma) Google hides certain categories of ads unless you are signed into a Google account. If you want these included, paste an authenticated cookie into the **userCookies** input. #### How to export your cookies 1. Install the **Cookie-Editor** browser extension. It is free, has over a million users, and is safe: [Chrome](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) or [Firefox](https://addons.mozilla.org/firefox/addon/cookie-editor/) 2. In the same browser, sign in at `https://adstransparency.google.com` using a **disposable Google account** (see warning below) 3. Browse around the site for a minute so Google sets its session cookies 4. Click the Cookie-Editor icon while you are still on the Transparency Center 5. Click **Export**, then **Export as JSON**, and copy what it gives you 6. Paste that JSON into the **userCookies** field on this actor That is it. Every request now goes through as that logged-in account. #### Safety notes - **Never use cookies from your real Google account.** The cookies give the scraper the same access a signed-in user has. Always create a throwaway Gmail, use it once, export, and forget about it. - **Cookies expire.** Google refreshes them every few days or weeks. If results drop off, re-export and paste fresh cookies. - **Expect tighter rate limits.** Signed-in requests have stricter limits. Keep runs small, and switch to Residential proxies if you start seeing blocks. - **Your input is encrypted.** Apify masks the cookie field in the UI and in logs. Still, treat it like a password. ### 🌐 Proxy settings By default the tool uses Apify's built-in proxies and rotates automatically. No setup needed. - **Automatic (default)**: Apify picks. Works for most runs. - **Datacenter**: Fastest and cheapest. - **Residential**: Use this if you start seeing "blocked" errors. Google treats residential IPs as real users. - **Your own proxies**: Paste your URLs. ### 💡 Good to know - You can mix websites, brand names, advertiser IDs, and links in the same run. - If a website matches more than one advertiser (like a big retailer with subsidiaries), the tool picks the one with the most ads. For small or niche brands, a brand name search works better. - Video ads come back with the real YouTube watch URL, plus the video ID and duration. To download the actual MP4, pass the URL into our [YouTube Video Downloader](https://apify.com/lurkapi/youtube-video-downloader). - Text ads on Google can come in two flavors. About 10 to 15 percent of the text ads from big advertisers give us a clean headline and description. For the rest, Google only shows a static image of the ad. Turn on **OCR** to read the text out of those images. The destination URL is never shown for text ads, only for image and video ads. - Landing page files are stored in your Apify key-value store as HTML, one per unique URL. You can preview each page directly from the dataset by clicking the `landingPageUrl` column. When opened in a browser, images and styles load from the original live site. - Files are stored in your Apify account. How long they stay there depends on your Apify plan. ### ❓ FAQ **My website returned no ads. Why?** Google matches ads to the company name, not the website. Try the brand name on its own (`Shopify` rather than `shopify.com`), or paste the advertiser ID directly. **Runs fail with "blocked after 5 proxy rotations". What do I do?** Google temporarily flagged the IPs the tool was using. Switch to Residential proxies in the Proxy Configuration input, or wait a few minutes and try again. **How long are downloaded images kept?** They live in your Apify storage. The retention period depends on your Apify plan. **Can I avoid paying for ads I already scraped?** Yes. Use the **Already seen** input (in the Narrow it down section). Paste the IDs of ads you have from previous runs in any format, commas or new lines or spaces, and the tool skips them. No row, no charge. Perfect for weekly or monthly tracking where you only want to pay for genuinely new ads. **Why is `destinationUrl` empty for most of my ads?** Google only exposes the destination URL for video ads. Text and image ads served as static snapshots in the Transparency Center do not include it. This applies to every tool that scrapes the Transparency Center. Google withholds the data at the source. **Do I pay for the same landing page twice?** No. The tool only downloads each unique URL once per run. If 50 of an advertiser's ads point to the same page, you pay $0.02 once and every row links to the same saved file. **Does this really work for political ads?** Yes. Flip on "Political only" and pick a country (this one filter will not work globally). You get spend, impressions, and the countries the ad ran in. Turn on **Targeting locations** to also get the ZIP codes and states the campaign targeted. **Can I download the actual video of a video ad?** Not directly here. Video ads go through YouTube, so this tool gives you the YouTube link. Pass that link into our [YouTube Video Downloader](https://apify.com/lurkapi/youtube-video-downloader) to grab the MP4. **Which platforms can I filter by?** Search, YouTube, Shopping, Maps, Play, or any of them. The platform is listed on every row. **Does OCR work in languages other than English?** Yes. The tool detects the language of each image on its own. No language setting needed, no configuration. It covers all major scripts (Latin, Cyrillic, Arabic, Chinese, Japanese, Korean, Hindi, Thai, Hebrew, Greek, and more). **How do I get only political ads?** Turn on "Political only" and set a specific country. The tool uses Google's political disclosure endpoint and returns only regulated political ads, with spend and impression data included. ### 🔗 Other tools you might like - [YouTube Video Downloader](https://apify.com/lurkapi/youtube-video-downloader): feed in the YouTube URL from any video ad and download the raw MP4. - [YouTube Transcript Download](https://apify.com/lurkapi/youtube-transcript-download): pull the full spoken transcript of any video ad for deeper analysis. - [YouTube Channel Videos & Stats Scraper](https://apify.com/lurkapi/youtube-channel-videos-stats-scraper): compare an advertiser's organic YouTube channel against their paid ads in one go. ### ⚖️ Disclaimer This tool is intended for personal, research, educational, journalistic, and compliance use. You are responsible for complying with Google's Terms of Service and the laws in your jurisdiction. The developer is not liable for misuse. Data availability depends on what Google's Ads Transparency Center shows at the time of your run. **Keywords**: google ads, ads transparency center, political ads, FEC, competitor ads, ad library, advertiser lookup, scrape google ads # Actor input Schema ## `advertiserIds` (type: `array`): The fastest and cheapest way to scrape. Paste one or more advertiser IDs (they always start with AR). Find the ID at the end of any advertiser URL on adstransparency.google.com, for example AR01625195283841286145 for Shopify. ## `domains` (type: `array`): Website domains. The advertiser with the most ads is auto-selected. Use 'searchTerms' or 'advertiserIds' for finer control. ## `searchTerms` (type: `array`): Advertiser names to search. Returns up to 'maxAdvertisersPerDomain' matches per term. ## `startUrls` (type: `array`): Paste any https://adstransparency.google.com/advertiser/... URL. ## `maxAdvertisersPerDomain` (type: `integer`): When you enter a website or brand name, how many matching advertisers to pull. Ignored when you paste advertiser IDs or Transparency Center links directly. ## `excludeCreativeIds` (type: `string`): Paste creative IDs you already have. The scraper skips them and charges you nothing for duplicates. Accepts any format: comma-separated, one per line, space-separated, copied from a CSV. Each ID looks like CR followed by digits (for example CR01195599340496748545). Ideal for weekly or monthly tracking runs where you only want to pay for ads you haven't seen before. ## `region` (type: `string`): Country to scrape. Pick 'Anywhere (global)' to return ads from every country at once. ## `platform` (type: `string`): Filter by the Google surface where the ad ran. ## `startDate` (type: `string`): Only return ads whose active window overlaps on or after this date (YYYY-MM-DD). Requires 'End date' too. ## `endDate` (type: `string`): Only return ads whose active window overlaps on or before this date (YYYY-MM-DD). Requires 'Start date' too. ## `politicalAdsOnly` (type: `boolean`): Return only political ads, with impression + spend disclosure fields. Requires 'Region' to be a country code (not 'anywhere'). ## `includeFormatText` (type: `boolean`): Return text ads (search and display copy). ## `includeFormatImage` (type: `boolean`): Return image/display ads. ## `includeFormatVideo` (type: `boolean`): Return video ads (YouTube and display video). ## `maxAdsPerAdvertiser` (type: `integer`): Cap on creatives scraped per advertiser. ## `fastMode` (type: `boolean`): Skip per-creative enrichment (variants, region stats, targeting) and iframe decoding (headline, description, destinationUrl, YouTube URL). Roughly 10x faster for large runs. Use when you only need the baseline ad list. ## `outputTargeting` (type: `boolean`): Include the ad's targeting profile: demographic, geography, and contextual include / exclude flags, plus raw criteria IDs. Works for commercial and political ads. ## `outputRegionStats` (type: `boolean`): Include per-region last-shown dates. For political ads, also includes per-region impression bands. ## `outputVariants` (type: `boolean`): Include all creative variations (A/B versions of the same ad). ## `outputDescription` (type: `boolean`): Include ad body/description text. ## `outputHeadline` (type: `boolean`): Include ad headline. ## `outputDestinationUrl` (type: `boolean`): Include the click-through URL. ## `includeRegionEnrichment` (type: `boolean`): See exactly which countries each ad ran in and when it was last seen in each one. For political ads, also get impression bands per country. Essential for international campaign research and regulatory audits. ## `includeMediaDownload` (type: `boolean`): Save every image ad as a PNG or JPEG file in your Apify storage. Perfect for building a competitor swipe file, running visual diffs over time, or feeding a design team fresh reference material. Video ads are not downloaded here: pass the YouTube URL from the 'videoUrl' field into our YouTube Video Downloader actor (https://apify.com/lurkapi/youtube-video-downloader) to grab the raw .mp4. ## `includeOcr` (type: `boolean`): Extract the full headline, description, and sitelinks from every image ad, even when Google does not expose them as structured fields. Auto-detects the language of each ad (English, Spanish, Chinese, Portuguese, French, German, Japanese, Arabic, Russian, Hindi, Italian, Korean, and 15+ more). No language setting needed. Essential if you want a searchable database of competitor ad copy. ## `includeLandingPage` (type: `boolean`): Download the full HTML of the page each ad links to and archive it in your Apify storage. You only pay once per unique page, even if 50 ads point to the same destination. Build a permanent, searchable archive of every landing page your competitors are driving traffic to. ## `includeTargetingLocations` (type: `boolean`): For political ads, turn Google's opaque targeting codes into readable ZIP codes, states, and countries. See exactly where a campaign was spending its ad dollars. Journalism gold for anyone covering political advertising. ## `shouldDownloadPreviews` (type: `boolean`): Archive each ad's live Google preview as a standalone HTML file in your Apify storage. The preview URL on each row is replaced with a permanent link that keeps working even after Google pulls the ad. Ideal for regulatory records, client reports, or visual audits. ## `userCookies` (type: `string`): Optional. Paste the JSON array exported from the Cookie-Editor browser extension after signing into adstransparency.google.com with a DISPOSABLE Google account. Unlocks alcohol, gambling, pharma, and other age-gated ads. Never paste cookies from your personal account, since someone with dataset access could potentially extract them. See the README for step-by-step export instructions. ## `proxyConfig` (type: `object`): Apify proxies. Switch to Residential if datacenter IPs get blocked. ## Actor input object example ```json { "advertiserIds": [], "domains": [ "shopify.com" ], "searchTerms": [], "startUrls": [], "maxAdvertisersPerDomain": 1, "region": "anywhere", "platform": "any", "politicalAdsOnly": false, "includeFormatText": true, "includeFormatImage": true, "includeFormatVideo": true, "maxAdsPerAdvertiser": 100, "fastMode": false, "outputTargeting": true, "outputRegionStats": true, "outputVariants": true, "outputDescription": true, "outputHeadline": true, "outputDestinationUrl": true, "includeRegionEnrichment": false, "includeMediaDownload": false, "includeOcr": false, "includeLandingPage": false, "includeTargetingLocations": false, "shouldDownloadPreviews": false, "proxyConfig": { "useApifyProxy": true, "apifyProxyGroups": [] } } ```` # Actor output Schema ## `dataset` (type: `string`): One row per ad. Six views available: Overview, Ad copy, Creative, Landing page, Political ads, Full. ## `keyValueStore` (type: `string`): Downloaded images, preview HTML snapshots, and archived landing pages (when the matching add-ons are enabled). # 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 = { "advertiserIds": [], "domains": [ "shopify.com" ], "searchTerms": [], "startUrls": [], "excludeCreativeIds": "", "region": "anywhere", "proxyConfig": { "useApifyProxy": true, "apifyProxyGroups": [] } }; // Run the Actor and wait for it to finish const run = await client.actor("lurkapi/google-ads-scraper").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 = { "advertiserIds": [], "domains": ["shopify.com"], "searchTerms": [], "startUrls": [], "excludeCreativeIds": "", "region": "anywhere", "proxyConfig": { "useApifyProxy": True, "apifyProxyGroups": [], }, } # Run the Actor and wait for it to finish run = client.actor("lurkapi/google-ads-scraper").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 '{ "advertiserIds": [], "domains": [ "shopify.com" ], "searchTerms": [], "startUrls": [], "excludeCreativeIds": "", "region": "anywhere", "proxyConfig": { "useApifyProxy": true, "apifyProxyGroups": [] } }' | apify call lurkapi/google-ads-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=lurkapi/google-ads-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Ads Scraper", "description": "Scrape Google Ads Transparency Center by advertiser ID, domain (auto-resolved), or search term. Optional OCR, landing-page scrape, media download.", "version": "0.0", "x-build-id": "KD32ZOTUDvBd49y4e" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lurkapi~google-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lurkapi-google-ads-scraper", "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/lurkapi~google-ads-scraper/runs": { "post": { "operationId": "runs-sync-lurkapi-google-ads-scraper", "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/lurkapi~google-ads-scraper/run-sync": { "post": { "operationId": "run-sync-lurkapi-google-ads-scraper", "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", "properties": { "advertiserIds": { "title": "Advertiser IDs", "maxItems": 100, "type": "array", "description": "The fastest and cheapest way to scrape. Paste one or more advertiser IDs (they always start with AR). Find the ID at the end of any advertiser URL on adstransparency.google.com, for example AR01625195283841286145 for Shopify.", "items": { "type": "string" } }, "domains": { "title": "Domains", "maxItems": 100, "type": "array", "description": "Website domains. The advertiser with the most ads is auto-selected. Use 'searchTerms' or 'advertiserIds' for finer control.", "items": { "type": "string" } }, "searchTerms": { "title": "Search terms", "maxItems": 100, "type": "array", "description": "Advertiser names to search. Returns up to 'maxAdvertisersPerDomain' matches per term.", "items": { "type": "string" } }, "startUrls": { "title": "Start URLs", "maxItems": 100, "type": "array", "description": "Paste any https://adstransparency.google.com/advertiser/... URL.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxAdvertisersPerDomain": { "title": "Max advertisers per website or brand name", "minimum": 1, "maximum": 20, "type": "integer", "description": "When you enter a website or brand name, how many matching advertisers to pull. Ignored when you paste advertiser IDs or Transparency Center links directly.", "default": 1 }, "excludeCreativeIds": { "title": "🔁 Already seen (pay only for new ads)", "maxLength": 100000, "type": "string", "description": "Paste creative IDs you already have. The scraper skips them and charges you nothing for duplicates. Accepts any format: comma-separated, one per line, space-separated, copied from a CSV. Each ID looks like CR followed by digits (for example CR01195599340496748545). Ideal for weekly or monthly tracking runs where you only want to pay for ads you haven't seen before." }, "region": { "title": "Region", "enum": [ "anywhere", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "BQ", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CK", "CR", "CI", "HR", "CW", "CY", "CZ", "CD", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "HN", "HK", "HU", "IS", "IN", "ID", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "RE", "RO", "RW", "SH", "KN", "LC", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "ES", "LK", "SR", "SJ", "SE", "CH", "TW", "TJ", "TZ", "TH", "BS", "GM", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "VI", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VA", "VE", "VN", "WF", "EH", "YE", "ZM", "ZW" ], "type": "string", "description": "Country to scrape. Pick 'Anywhere (global)' to return ads from every country at once.", "default": "anywhere" }, "platform": { "title": "Platform", "enum": [ "any", "SEARCH", "YOUTUBE", "SHOPPING", "MAPS", "PLAY" ], "type": "string", "description": "Filter by the Google surface where the ad ran.", "default": "any" }, "startDate": { "title": "Start date", "type": "string", "description": "Only return ads whose active window overlaps on or after this date (YYYY-MM-DD). Requires 'End date' too." }, "endDate": { "title": "End date", "type": "string", "description": "Only return ads whose active window overlaps on or before this date (YYYY-MM-DD). Requires 'Start date' too." }, "politicalAdsOnly": { "title": "Political ads only", "type": "boolean", "description": "Return only political ads, with impression + spend disclosure fields. Requires 'Region' to be a country code (not 'anywhere').", "default": false }, "includeFormatText": { "title": "Include text ads", "type": "boolean", "description": "Return text ads (search and display copy).", "default": true }, "includeFormatImage": { "title": "Include image ads", "type": "boolean", "description": "Return image/display ads.", "default": true }, "includeFormatVideo": { "title": "Include video ads", "type": "boolean", "description": "Return video ads (YouTube and display video).", "default": true }, "maxAdsPerAdvertiser": { "title": "Max ads per advertiser", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on creatives scraped per advertiser.", "default": 100 }, "fastMode": { "title": "⚡ Fast mode", "type": "boolean", "description": "Skip per-creative enrichment (variants, region stats, targeting) and iframe decoding (headline, description, destinationUrl, YouTube URL). Roughly 10x faster for large runs. Use when you only need the baseline ad list.", "default": false }, "outputTargeting": { "title": "Targeting", "type": "boolean", "description": "Include the ad's targeting profile: demographic, geography, and contextual include / exclude flags, plus raw criteria IDs. Works for commercial and political ads.", "default": true }, "outputRegionStats": { "title": "Region stats", "type": "boolean", "description": "Include per-region last-shown dates. For political ads, also includes per-region impression bands.", "default": true }, "outputVariants": { "title": "Variants", "type": "boolean", "description": "Include all creative variations (A/B versions of the same ad).", "default": true }, "outputDescription": { "title": "Description", "type": "boolean", "description": "Include ad body/description text.", "default": true }, "outputHeadline": { "title": "Headline", "type": "boolean", "description": "Include ad headline.", "default": true }, "outputDestinationUrl": { "title": "Destination URL", "type": "boolean", "description": "Include the click-through URL.", "default": true }, "includeRegionEnrichment": { "title": "🌍 Per-country breakdown", "type": "boolean", "description": "See exactly which countries each ad ran in and when it was last seen in each one. For political ads, also get impression bands per country. Essential for international campaign research and regulatory audits.", "default": false }, "includeMediaDownload": { "title": "🖼️ Download the ad image", "type": "boolean", "description": "Save every image ad as a PNG or JPEG file in your Apify storage. Perfect for building a competitor swipe file, running visual diffs over time, or feeding a design team fresh reference material. Video ads are not downloaded here: pass the YouTube URL from the 'videoUrl' field into our YouTube Video Downloader actor (https://apify.com/lurkapi/youtube-video-downloader) to grab the raw .mp4.", "default": false }, "includeOcr": { "title": "🔤 Read the text inside the image", "type": "boolean", "description": "Extract the full headline, description, and sitelinks from every image ad, even when Google does not expose them as structured fields. Auto-detects the language of each ad (English, Spanish, Chinese, Portuguese, French, German, Japanese, Arabic, Russian, Hindi, Italian, Korean, and 15+ more). No language setting needed. Essential if you want a searchable database of competitor ad copy.", "default": false }, "includeLandingPage": { "title": "💾 Save the landing page", "type": "boolean", "description": "Download the full HTML of the page each ad links to and archive it in your Apify storage. You only pay once per unique page, even if 50 ads point to the same destination. Build a permanent, searchable archive of every landing page your competitors are driving traffic to.", "default": false }, "includeTargetingLocations": { "title": "📍 Decode political targeting", "type": "boolean", "description": "For political ads, turn Google's opaque targeting codes into readable ZIP codes, states, and countries. See exactly where a campaign was spending its ad dollars. Journalism gold for anyone covering political advertising.", "default": false }, "shouldDownloadPreviews": { "title": "🎨 Save the ad preview as HTML", "type": "boolean", "description": "Archive each ad's live Google preview as a standalone HTML file in your Apify storage. The preview URL on each row is replaced with a permanent link that keeps working even after Google pulls the ad. Ideal for regulatory records, client reports, or visual audits.", "default": false }, "userCookies": { "title": "Authentication cookies (for restricted ads)", "type": "string", "description": "Optional. Paste the JSON array exported from the Cookie-Editor browser extension after signing into adstransparency.google.com with a DISPOSABLE Google account. Unlocks alcohol, gambling, pharma, and other age-gated ads. Never paste cookies from your personal account, since someone with dataset access could potentially extract them. See the README for step-by-step export instructions." }, "proxyConfig": { "title": "Proxy configuration", "type": "object", "description": "Apify proxies. Switch to Residential if datacenter IPs get blocked.", "default": { "useApifyProxy": true, "apifyProxyGroups": [] } } } }, "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 } } } } } } } } } } ```