{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper & Ad Monitor", "description": "Monitor competitor Google ads: export any advertiser's Search, YouTube, Shopping, Maps & Play ads from the Ads Transparency Center with headlines, OCR text for image ads, CTAs, regions and first/last shown dates. Monitor mode outputs only new or changed ads. No login.", "version": "0.2", "x-build-id": "zt8FwK0vhgXVyTQpb" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/singletonops~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-singletonops-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/singletonops~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-singletonops-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/singletonops~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-singletonops-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": { "advertisers": { "title": "Advertisers (name, domain, ID, or URL)", "type": "array", "description": "One advertiser per line. Accepts an advertiser name (e.g. Nike), a domain (e.g. nike.com — returns every advertiser running ads for that site), an advertiser ID (e.g. AR16735076323512287233), or a pasted Transparency Center URL (advertiser or domain page). Names are resolved to the best-matching advertiser with the most ads; use the ID for an exact match.", "items": { "type": "string" } }, "searchTerms": { "title": "Search terms (find advertisers)", "type": "array", "description": "Keywords to look up in the Transparency Center search box (e.g. running shoes, insurance). Each term is resolved to the top matching advertisers (see the next field) and their ads are scraped. Note: Google's Transparency Center searches advertiser names and domains, not ad text.", "items": { "type": "string" } }, "maxAdvertisersPerSearchTerm": { "title": "Max advertisers per search term", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many top-matching advertisers to scrape for each search term.", "default": 3 }, "maxAds": { "title": "Max ads per advertiser / domain", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Maximum number of ads to scrape for each advertiser, domain, or resolved search-term advertiser. In monitor mode, unchanged ads are checked but not saved.", "default": 100 }, "region": { "title": "Region (country)", "enum": [ "anywhere", "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CX", "CC", "CO", "KM", "CK", "CR", "CI", "HR", "CU", "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", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IQ", "IE", "IR", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "XK", "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", "KP", "MP", "NO", "OM", "PK", "PW", "PA", "PG", "PY", "CN", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "GM", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "PS", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TH", "MK", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "TZ", "UM", "US", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "type": "string", "description": "Only ads shown in this country. Choose Anywhere for all regions.", "default": "anywhere" }, "dateFrom": { "title": "Shown from (date)", "type": "string", "description": "Only ads shown on or after this date. Absolute (YYYY-MM-DD) or relative (e.g. 30 days = last 30 days). Leave empty for no limit." }, "dateTo": { "title": "Shown until (date)", "type": "string", "description": "Only ads shown on or before this date (inclusive). Leave empty for today." }, "format": { "title": "Ad format", "enum": [ "ALL", "TEXT", "IMAGE", "VIDEO" ], "type": "string", "description": "Only ads of this format.", "default": "ALL" }, "platform": { "title": "Platform", "enum": [ "ALL", "SEARCH", "YOUTUBE", "SHOPPING", "MAPS", "PLAY" ], "type": "string", "description": "Only ads shown on this Google platform. (The Transparency Center has no separate Display filter; Display ads appear under All platforms.)", "default": "ALL" }, "longRunningOnly": { "title": "Long-running ads only (6+ months)", "type": "boolean", "description": "Keep only ads that have been running for at least 180 days (daysRunning ≥ 180), the \"proven winners\" a competitor keeps paying for. Same as Minimum days running = 180; if both are set, the larger value wins. Ads without a Google first/last shown date are dropped while this is on. Filtered-out ads are not saved or charged; Max ads still counts every ad checked, so raise it to find more long-running ads.", "default": false }, "minDaysRunning": { "title": "Minimum days running", "minimum": 0, "maximum": 3650, "type": "integer", "description": "Keep only ads whose daysRunning (last shown date minus first shown date, counting both days) is at least this many days, e.g. 90 or 180. 0 = off (default). Applied after the dates are read, so it works with every other filter. Ads without dates are dropped while the filter is on.", "default": 0 }, "includeCreativeDetails": { "title": "Include creative details (recommended)", "type": "boolean", "description": "Fetch each ad's detail and preview: headline, description, call to action, display URL / landing domain, image and YouTube video URLs, every region with first/last shown dates, platforms, impression ranges (where Google publishes them, e.g. EU) and number of variants. Turn off for a ~3-5x faster, cheaper list of ads (IDs, format, dates, preview image).", "default": true }, "extractTextFromImages": { "title": "Extract text from image-only text ads (OCR)", "type": "boolean", "description": "Many text ads are archived by Google only as a screenshot. When on, the actor reads the headline, description and display URL from that image with OCR (only for TEXT ads that have no text in their preview; requires creative details). OCR fields are marked with textSource = \"ocr\". Results are cached per creative, so monitor reruns never redo OCR.", "default": true }, "ocrLanguages": { "title": "OCR languages", "type": "array", "description": "Languages the OCR model should recognise. More languages = better accents/umlauts across markets but slightly more memory and time. Default: English, German, French, Spanish, Italian, Dutch, Portuguese, Polish.", "items": { "type": "string", "enum": [ "eng", "deu", "fra", "spa", "ita", "nld", "por", "pol", "swe", "dan", "nor", "fin", "ces", "slk", "slv", "hrv", "hun", "ron", "bul", "ell", "rus", "ukr", "tur", "lit", "lav", "est", "cat", "srp", "srp_latn", "ind", "vie", "msa", "tgl" ], "enumTitles": [ "English", "German", "French", "Spanish", "Italian", "Dutch", "Portuguese", "Polish", "Swedish", "Danish", "Norwegian", "Finnish", "Czech", "Slovak", "Slovenian", "Croatian", "Hungarian", "Romanian", "Bulgarian", "Greek", "Russian", "Ukrainian", "Turkish", "Lithuanian", "Latvian", "Estonian", "Catalan", "Serbian (Cyrillic)", "Serbian (Latin)", "Indonesian", "Vietnamese", "Malay", "Tagalog" ] }, "default": [ "eng", "deu", "fra", "spa", "ita", "nld", "por", "pol" ] }, "detectPlatforms": { "title": "Detect platforms for every ad", "type": "boolean", "description": "Google publishes per-platform stats only for some regions (mostly the EU). With this on, the Actor also lists each advertiser once per platform filter (Search, YouTube, Shopping, Maps, Play) and tags every ad with the platforms it appears on. Adds a few cheap list requests per query; only used when Platform = All and creative details are on.", "default": true }, "includeRawData": { "title": "Include raw API data", "type": "boolean", "description": "Adds a raw field with the unprocessed Transparency Center responses. Useful for debugging or custom parsing; makes items much larger.", "default": false }, "onlyNewOrChanged": { "title": "Monitoring mode: only new or changed ads", "type": "boolean", "description": "Remembers what each query returned last time (in a named key-value store) and saves only ads that are new, whose content/reach changed, or that stopped running. Every item gets changeType and changedFields. Schedule the Actor daily or weekly to get competitor-ad alerts. Keep filters identical between runs.", "default": false }, "emitBaselineOnFirstRun": { "title": "Save all ads on the first monitoring run", "type": "boolean", "description": "On the first monitoring run every ad is new. Turn off to just record a silent baseline and only get truly new/changed ads from the next run on.", "default": true }, "reportStoppedAds": { "title": "Report ads that stop running", "type": "boolean", "description": "Monitoring mode only. Saves an ad once with changeType: \"stopped\" when its lastShown date stops advancing (see the next setting), or when it disappears from a complete listing for 2 runs in a row. If it runs again later it comes back as changed with changedFields: [\"running\"]. Stopped rows are saved ads like any other.", "default": true }, "stoppedAfterDays": { "title": "Treat an ad as stopped after (days)", "minimum": 1, "maximum": 90, "type": "integer", "description": "Monitoring mode only. An ad whose last shown date is at least this many days old (and did not advance since the previous run) is reported as stopped. Google updates last shown dates with some delay, so values under 2 can cause noise.", "default": 3 }, "stateStoreName": { "title": "Monitoring state store name", "type": "string", "description": "Named key-value store that keeps monitoring snapshots between runs. Use different names to keep independent monitors (e.g. one per client).", "default": "google-ads-transparency-monitor" }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Google aggressively rate-limits datacenter IPs on the Transparency Center. The default Apify Residential proxy is the most reliable and, because only small JSON API responses go through it (ad previews are fetched directly), it adds only about one or two cents per 1,000 ads. Datacenter or your own proxies work too — see the fallback option below.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "proxyFallbackToResidential": { "title": "Fall back to residential proxy when rate-limited", "type": "boolean", "description": "If the selected proxy (or no proxy) keeps getting rate-limited by Google, switch to Apify Residential proxy for the rest of the run instead of returning ads without details. Has no effect when Residential is already selected.", "default": true }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "Parallel detail requests. Higher is faster but more likely to be rate-limited.", "default": 4 }, "maxRetries": { "title": "Max retries per request", "minimum": 0, "maximum": 10, "type": "integer", "description": "Retries with exponential backoff and proxy-session rotation on rate limits, timeouts and server errors.", "default": 6 }, "requestTimeoutSecs": { "title": "Request timeout (seconds)", "minimum": 5, "maximum": 120, "type": "integer", "description": "Timeout for each HTTP request.", "default": 30 }, "feedback": { "title": "Feedback for the developer (optional)", "type": "string", "description": "Anything missing or wrong? Write it here. It is stored in this run's QUALITY_REPORT, which the maintainers review weekly to improve the Actor. Please don't include personal data." }, "reportIssueWebhook": { "title": "Issue report webhook URL (optional)", "type": "string", "description": "If set, the Actor POSTs a JSON report (run summary + QUALITY_REPORT + your feedback) to this URL when the run has errors, partial results, or feedback. Handy for Slack/Zapier/Make alerts." } } }, "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 } } } } } } } } } }