{ "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 } } } } } } } } } }