{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper - Competitor Ads", "description": "Scrape Google Ads Transparency Center creatives by advertiser name, AR ID, domain or URL: ad text (headline/description), images, YouTube videos, regions, impression ranges, platforms and first/last shown dates. Monitoring mode detects new and stopped ads. Fast HTTP, no browser.", "version": "1.0", "x-build-id": "6GZ5Lfs5V3nuogVTM" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/adyg~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-adyg-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/adyg~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-adyg-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/adyg~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-adyg-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", "required": [ "targets" ], "properties": { "targets": { "title": "Advertisers, domains or Transparency URLs", "type": "array", "description": "One per line. Accepts: an advertiser name (Nike), an advertiser ID (AR16735076323512287233), a website domain (grammarly.com - returns every advertiser running ads for that site), or any Ads Transparency Center URL (advertiser page, single creative page, or a domain search; filters in the URL such as region, platform, format and dates are respected).", "default": [ "Nike" ], "items": { "type": "string" } }, "maxAdsPerTarget": { "title": "Max ads per advertiser / domain", "minimum": 1, "maximum": 20000, "type": "integer", "description": "How many ad creatives to return for each target, newest (most recently shown) first. Big brands have thousands of ads.", "default": 50 }, "region": { "title": "Region (where the ad was shown)", "enum": [ "anywhere", "AF", "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", "CV", "KH", "CM", "CA", "IC", "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", "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", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "RE", "RO", "RW", "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", "SD", "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": "Only ads shown in this country. Anywhere = all regions.", "default": "anywhere" }, "lastDays": { "title": "Shown in the last N days", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Only ads shown at least once in the last N days (e.g. 30). Overrides the date range below." }, "dateFrom": { "title": "Shown from (date)", "type": "string", "description": "Only ads shown on or after this date (YYYY-MM-DD). Data starts in 2018." }, "dateTo": { "title": "Shown until (date)", "type": "string", "description": "Only ads shown on or before this date (YYYY-MM-DD). Default: today." }, "formats": { "title": "Ad formats", "type": "array", "description": "Leave empty for all formats.", "items": { "type": "string", "enum": [ "TEXT", "IMAGE", "VIDEO" ], "enumTitles": [ "Text", "Image", "Video" ] } }, "platforms": { "title": "Platforms", "type": "array", "description": "Leave empty for all platforms (this also includes Display-network ads, which have no separate filter in the Transparency Center).", "items": { "type": "string", "enum": [ "GOOGLE_SEARCH", "YOUTUBE", "GOOGLE_SHOPPING", "GOOGLE_MAPS", "GOOGLE_PLAY" ], "enumTitles": [ "Google Search", "YouTube", "Google Shopping", "Google Maps", "Google Play" ] } }, "includeDetails": { "title": "Include regions, impressions & platforms", "type": "boolean", "description": "Open each ad's detail record: every region it ran in with first/last shown dates, impression ranges and per-platform breakdown (impressions and platforms are published for EU/EEA regions), topic and targeting categories. Turn off for a faster list-only scrape.", "default": true }, "extractAdText": { "title": "Extract ad text (headline, description, URLs)", "type": "boolean", "description": "Read headline, description, call to action, display/landing URL, YouTube video ID and image URLs from the ad previews.", "default": true }, "ocrTextAds": { "title": "OCR text ads stored as images", "type": "boolean", "description": "Google archives most Search text ads only as a rendered image. With this on, the Actor reads the headline, description, display URL and sitelinks from that image with OCR (marked textSource: \"ocr\").", "default": true }, "ocrLanguage": { "title": "OCR language", "enum": [ "auto", "eng", "deu", "fra", "spa", "ita", "por", "nld", "pol", "swe", "dan", "nor", "fin", "tur", "ces", "slk", "ron", "hun", "hrv", "ind", "vie", "rus", "ukr", "ell", "jpn", "kor", "chi_sim", "chi_tra", "ara", "heb", "hin", "tha" ], "type": "string", "description": "Language model used to read text ads archived as images. Automatic picks the language of the selected region, of the countries the ad ran in, or of the domain (e.g. zalando.de -> German), and English otherwise. Latin-script models read English text too.", "default": "auto" }, "advertiserSummary": { "title": "Add a summary row per advertiser", "type": "boolean", "description": "One extra row per advertiser (type: \"summary\") with active ad count, total ads estimate, format and platform mix and top regions. Summary rows are free.", "default": true }, "maxAdvertisersPerName": { "title": "Advertisers per name", "minimum": 1, "maximum": 10, "type": "integer", "description": "A name can match several advertiser accounts (e.g. regional subsidiaries). How many of the best matches to scrape.", "default": 1 }, "monitorMode": { "title": "Monitoring mode: output only new and stopped ads", "type": "boolean", "description": "Compares each target with the previous run (state kept in a named key-value store) and outputs only ads that are NEW since the last run or have STOPPED running (changeType field). Schedule the Actor daily or weekly for competitor-ad alerts.", "default": false }, "monitorStoreName": { "title": "Monitoring state store name", "type": "string", "description": "Named key-value store that keeps the last-seen ads per target. Use different names to keep independent watch lists.", "default": "google-ads-transparency-monitor" }, "activeWithinDays": { "title": "Ad counts as active if shown within (days)", "minimum": 1, "maximum": 365, "type": "integer", "description": "An ad whose last-shown date is older than this is treated as inactive (isActive: false) and, in monitoring mode, reported as STOPPED.", "default": 7 }, "emitBaselineOnFirstRun": { "title": "Output all ads on the first monitoring run", "type": "boolean", "description": "On the first run for a target there is nothing to compare with, so every current ad is reported as NEW. Turn off to silently store the baseline and only report changes from the second run on.", "default": true }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy is used by default (datacenter first, automatic residential fallback if Google throttles).", "default": { "useApifyProxy": true } }, "residentialFallback": { "title": "Fall back to residential proxy", "type": "boolean", "description": "If datacenter IPs are throttled, retry through Apify residential proxy automatically.", "default": true }, "maxConcurrency": { "title": "Max concurrent requests", "minimum": 1, "maximum": 30, "type": "integer", "description": "Parallel requests to the Transparency Center.", "default": 8 }, "dataForSeoFallback": { "title": "Backup data source (DataForSEO)", "type": "boolean", "description": "Only for self-hosted copies with DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD environment variables: if the Transparency Center request fails, fetch the ad list from DataForSEO instead (list data only).", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "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 } } } } } } } } } }