{ "openapi": "3.0.1", "info": { "title": "Google Ads Scraper โ€” Ads Transparency Center", "description": "Scrape the Google Ads Transparency Center by brand, advertiser website or advertiser ID. Get every creative variation, first/last shown dates, per-country impression reach by Google surface, verified advertiser identity, EU audience targeting and election-ad spend. 222 countries, no login.", "version": "0.1", "x-build-id": "sUE9FaWByPlT0YAdr" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/corvuslab~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-corvuslab-google-ads-transparency-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/corvuslab~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-corvuslab-google-ads-transparency-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/corvuslab~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-corvuslab-google-ads-transparency-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": { "query": { "title": "๐Ÿ”‘ Search query", "type": "string", "description": "Brand name, advertiser website or advertiser ID. Separate multiple searches with commas โ€” each runs on its own and results are merged and de-duplicated. Leave empty and the run falls back to a sample search so you always get rows." }, "startUrls": { "title": "๐Ÿ“‹ Start URLs", "type": "array", "description": "Paste Ads Transparency Center URLs directly โ€” an advertiser page, a single ad page, or a search URL. Region is read from the URL when present.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxResults": { "title": "๐Ÿ”ข Max results", "minimum": 0, "type": "integer", "description": "Maximum number of ads to return. Set 0 for unlimited (bounded by how many the search has).", "default": 50 }, "ignoreUrlFailures": { "title": "โญ๏ธ Ignore URL failures", "type": "boolean", "description": "Skip URLs that cannot be interpreted instead of failing the whole run.", "default": true }, "regions": { "title": "๐ŸŒ Countries", "type": "array", "description": "Only return ads shown in these countries. Leave empty to search worldwide.", "items": { "type": "string", "enum": [ "US", "GB", "CA", "AU", "DE", "FR", "ES", "IT", "NL", "BR", "MX", "IN", "JP", "SE", "DK", "NO", "PL", "IE", "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AR", "AS", "AT", "AW", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BS", "BT", "BW", "BY", "BZ", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CY", "CZ", "DJ", "DM", "DO", "DZ", "EC", "EE", "EG", "ER", "ET", "FI", "FJ", "FM", "FO", "GA", "GD", "GE", "GG", "GH", "GI", "GL", "GM", "GN", "GQ", "GR", "GT", "GU", "GW", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IL", "IM", "IQ", "IS", "JE", "JM", "JO", "KE", "KG", "KH", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PR", "PS", "PT", "PW", "PY", "QA", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SG", "SI", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TG", "TH", "TJ", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WS", "YE", "ZA", "ZM", "ZW" ], "enumTitles": [ "United States", "United Kingdom", "Canada", "Australia", "Germany", "France", "Spain", "Italy", "Netherlands", "Brazil", "Mexico", "India", "Japan", "Sweden", "Denmark", "Norway", "Poland", "Ireland", "Andorra", "United Arab Emirates", "Afghanistan", "Antigua & Barbuda", "Anguilla", "Albania", "Armenia", "Angola", "Argentina", "American Samoa", "Austria", "Aruba", "Azerbaijan", "Bosnia & Herzegovina", "Barbados", "Bangladesh", "Belgium", "Burkina Faso", "Bulgaria", "Bahrain", "Burundi", "Benin", "Bermuda", "Brunei", "Bolivia", "Bahamas", "Bhutan", "Botswana", "Belarus", "Belize", "Congo (DRC)", "Central African Republic", "Congo (Republic)", "Switzerland", "Cote d'Ivoire", "Cook Islands", "Chile", "Cameroon", "China", "Colombia", "Costa Rica", "Cuba", "Cabo Verde", "Curacao", "Cyprus", "Czechia", "Djibouti", "Dominica", "Dominican Republic", "Algeria", "Ecuador", "Estonia", "Egypt", "Eritrea", "Ethiopia", "Finland", "Fiji", "Micronesia", "Faroe Islands", "Gabon", "Grenada", "Georgia", "Guernsey", "Ghana", "Gibraltar", "Greenland", "Gambia", "Guinea", "Equatorial Guinea", "Greece", "Guatemala", "Guam", "Guinea-Bissau", "Guyana", "Hong Kong", "Honduras", "Croatia", "Haiti", "Hungary", "Indonesia", "Israel", "Isle of Man", "Iraq", "Iceland", "Jersey", "Jamaica", "Jordan", "Kenya", "Kyrgyzstan", "Cambodia", "Kiribati", "Comoros", "St. Kitts & Nevis", "South Korea", "Kuwait", "Cayman Islands", "Kazakhstan", "Laos", "Lebanon", "St. Lucia", "Liechtenstein", "Sri Lanka", "Liberia", "Lesotho", "Lithuania", "Luxembourg", "Latvia", "Libya", "Morocco", "Monaco", "Moldova", "Montenegro", "Madagascar", "Marshall Islands", "North Macedonia", "Mali", "Myanmar", "Mongolia", "Macao", "Northern Mariana Islands", "Martinique", "Mauritania", "Montserrat", "Malta", "Mauritius", "Maldives", "Malawi", "Malaysia", "Mozambique", "Namibia", "New Caledonia", "Niger", "Norfolk Island", "Nigeria", "Nicaragua", "Nepal", "Nauru", "Niue", "New Zealand", "Oman", "Panama", "Peru", "French Polynesia", "Papua New Guinea", "Philippines", "Pakistan", "Puerto Rico", "Palestine", "Portugal", "Palau", "Paraguay", "Qatar", "Romania", "Serbia", "Russia", "Rwanda", "Saudi Arabia", "Solomon Islands", "Seychelles", "Sudan", "Singapore", "Slovenia", "Slovakia", "Sierra Leone", "San Marino", "Senegal", "Somalia", "Suriname", "South Sudan", "Sao Tome & Principe", "El Salvador", "Sint Maarten", "Syria", "Eswatini", "Turks & Caicos", "Chad", "Togo", "Thailand", "Tajikistan", "Timor-Leste", "Turkmenistan", "Tunisia", "Tonga", "Turkiye", "Trinidad & Tobago", "Tuvalu", "Taiwan", "Tanzania", "Ukraine", "Uganda", "Uruguay", "Uzbekistan", "Vatican City", "St. Vincent & Grenadines", "Venezuela", "British Virgin Islands", "U.S. Virgin Islands", "Vietnam", "Vanuatu", "Samoa", "Yemen", "South Africa", "Zambia", "Zimbabwe" ] } }, "platforms": { "title": "๐Ÿ“บ Platforms", "type": "array", "description": "Only return ads that ran on these Google surfaces. Leave empty for all of them.", "items": { "type": "string", "enum": [ "google_search", "youtube", "google_shopping", "google_maps", "google_play" ], "enumTitles": [ "๐Ÿ” Google Search", "โ–ถ๏ธ YouTube", "๐Ÿ›๏ธ Google Shopping", "๐Ÿ“ Google Maps", "๐Ÿ“ฑ Google Play" ] } }, "adFormat": { "title": "๐Ÿ–ผ๏ธ Ad format", "enum": [ "any", "text", "image", "video" ], "type": "string", "description": "Only return ads of this creative type.", "default": "any" }, "dateFrom": { "title": "๐Ÿ“… Shown from", "type": "string", "description": "Only return ads shown on or after this date (YYYY-MM-DD). Leave empty for no lower bound." }, "dateTo": { "title": "๐Ÿ“† Shown until", "type": "string", "description": "Only return ads shown on or before this date (YYYY-MM-DD). Leave empty for no upper bound." }, "politicalAdsOnly": { "title": "๐Ÿ—ณ๏ธ Election ads only", "type": "boolean", "description": "Switch to the election-ads surface, where Google discloses who paid for the ad plus its spend and impression ranges. Works with no search query โ€” it browses every election ad in the selected countries.", "default": false }, "includeDetails": { "title": "๐Ÿ”ฌ Fetch full ad details", "type": "boolean", "description": "Fetch each ad's detail record for all variations, per-country impressions, audience selection and verified advertiser identity. Turn off for the fastest, cheapest runs.", "default": true }, "includeVideoDetails": { "title": "๐ŸŽฌ Resolve video ads (YouTube ID + thumbnail)", "type": "boolean", "description": "Video ads have no image - only a Google-hosted preview script. Turn this on to also return the ad's YouTube video ID, a watch URL and a thumbnail image, so video creatives are viewable straight from the export. Costs one extra request per video ad.", "default": true }, "includeAdCopy": { "title": "โœ๏ธ Include ad copy & landing pages", "type": "boolean", "description": "Extract what the ad actually says and where it points: headline, description, call-to-action, display URL, landing page, and the product title + merchant on Shopping ads. Text-ad copy comes back as real text - no OCR, nothing to clean up. Adds one lightweight request per ad on a separate rate budget, so it does not slow the main scrape. Turn off for the fastest possible run.", "default": true }, "includeAdvertiserTotals": { "title": "๐Ÿ“Š Advertiser ad-library size", "type": "boolean", "description": "Add how many ads each advertiser is running in total (advertiserTotalAdsLowerBound / UpperBound) - the whole-library count, not just the ads this run returned. One cheap extra request per advertiser.", "default": true }, "compact": { "title": "๐Ÿ“ฆ Compact records", "type": "boolean", "description": "Emit only the core ad fields. Ideal for AI agents and MCP clients.", "default": false }, "excludeEmptyFields": { "title": "๐Ÿงน Drop empty fields", "type": "boolean", "description": "Remove null, empty-string and empty-array fields from each record.", "default": false }, "incrementalMode": { "title": "โ™ป๏ธ Incremental mode", "type": "boolean", "description": "Track state between runs and tag every record with a changeType (NEW / UPDATED / UNCHANGED / EXPIRED).", "default": false }, "stateKey": { "title": "๐Ÿ—๏ธ State key", "type": "string", "description": "Stable name for the tracked search. Leave empty to derive one automatically from your search settings." }, "emitUnchanged": { "title": "๐Ÿ” Include unchanged records", "type": "boolean", "description": "Also emit records that have not changed since the previous run.", "default": false }, "emitExpired": { "title": "๐Ÿ—‘๏ธ Include expired records", "type": "boolean", "description": "Emit records for items present last run but gone now.", "default": false }, "telegramToken": { "title": "๐Ÿ’ฌ Telegram bot token", "type": "string", "description": "Bot token from @BotFather." }, "telegramChatId": { "title": "๐Ÿ†” Telegram chat ID", "type": "string", "description": "Chat or channel ID, e.g. \"-100123456789\" or \"@yourchannel\"." }, "slackWebhookUrl": { "title": "๐Ÿ’ผ Slack webhook URL", "type": "string", "description": "Slack incoming-webhook URL." }, "discordWebhookUrl": { "title": "๐ŸŽฎ Discord webhook URL", "type": "string", "description": "Discord incoming-webhook URL." }, "webhookUrl": { "title": "๐Ÿช Webhook URL", "type": "string", "description": "Any HTTPS endpoint. Receives a JSON POST with the matched records โ€” works with n8n, Make and Zapier." }, "webhookHeaders": { "title": "๐Ÿงพ Webhook headers", "type": "object", "description": "Extra headers for the webhook request, e.g. {\"Authorization\": \"Bearer xyz\"}." }, "notificationLimit": { "title": "๐Ÿ”ข Records per notification", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many records to include in each notification message.", "default": 5 }, "clayWebhookUrl": { "title": "๐Ÿงฑ Clay webhook URL", "type": "string", "description": "Paste the webhook URL of a Clay table. In Clay: open the table โ†’ Actions โ†’ Import โ†’ Import data from webhook (or + Add โ†’ Webhooks โ†’ Monitor webhook), then copy the generated URL. Each ad arrives as its own row. Nested columns (regionsShown, countryStats, variants) arrive as JSON text so a Clay formula column can parse them." }, "clayAuthToken": { "title": "๐Ÿ”‘ Clay webhook auth token", "type": "string", "description": "Optional. Only needed if you enabled an authentication token on the Clay webhook source. Sent as the 'x-clay-webhook-auth' header." }, "notionApiKey": { "title": "๐Ÿ““ Notion integration token", "type": "string", "description": "Optional. Create an internal integration at notion.so/my-integrations, copy its Internal Integration Secret (starts with 'ntn_'), then open the target database โ†’ โ‹ฏ โ†’ Connections โ†’ and connect that integration. Without that last step Notion returns 'object_not_found'." }, "notionDatabaseId": { "title": "๐Ÿ—‚๏ธ Notion database ID or URL", "type": "string", "description": "Optional. Paste the database's URL or its 32-character ID. Every ad becomes one page in that database. The database can start completely empty โ€” the columns are created for you on the first run." }, "notionCreateProperties": { "title": "๐Ÿ› ๏ธ Create missing Notion columns", "type": "boolean", "description": "Add any columns the target database is missing (with the right Notion type) on the first run. Turn this off to write only into columns you created yourself โ€” fields with no matching column are then skipped.", "default": true }, "proxyConfiguration": { "title": "๐ŸŒ Proxy configuration", "type": "object", "description": "Apify Proxy is ON by default and should stay on. The source limits how fast a single IP can read ad details, so running direct returns fewer fully-detailed ads and takes far longer. Measured on the same 300-ad job: proxy on = 100% of ads fully detailed in ~2 minutes; direct = 73% in ~8.5 minutes. If proxy is unavailable the Actor falls back to a direct connection automatically.", "default": { "useApifyProxy": true } }, "rotateProxyIps": { "title": "๐Ÿ” Rotate proxy IP per request", "type": "boolean", "description": "Only applies when a proxy is enabled above. The source limits how fast a single IP may ask for ad details, so one IP for the whole run is what gets throttled. Rotating spreads requests across the proxy pool and can substantially increase how many ads come back fully detailed on large runs.", "default": true }, "maxRequestRetries": { "title": "๐Ÿ”„ Max request retries", "minimum": 0, "maximum": 10, "type": "integer", "description": "How many times to retry a failed request before giving up on it.", "default": 3 }, "detailConcurrency": { "title": "โšก Detail concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many ad detail requests to run in parallel. Lower it if the source starts refusing requests.", "default": 5 } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }