{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper — Ads, Text, Regions & Reach", "description": "Scrape the Google Ads Transparency Center: every Search, YouTube, Shopping, Maps & Play ad of any advertiser or website — text, image/video, first/last shown, regions, reach, targeting, landing page and political ad spend. Filter by region, platform, format and dates. Monitor new ads.", "version": "0.1", "x-build-id": "doIynFUgjD6wkHEB7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/griffie~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-griffie-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/griffie~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-griffie-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/griffie~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-griffie-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": { "queries": { "title": "Advertisers, websites or URLs", "type": "array", "description": "One per line. Each entry is auto-detected: an advertiser name (e.g. Nike), a website domain (nike.com), an advertiser ID (AR16735076323512287233), or any Ads Transparency Center URL (advertiser page, single ad, or a website search — filters in the URL such as region/format/platform are applied).", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Advertiser IDs (start with AR…). Same as putting them in the list above.", "items": { "type": "string" } }, "domains": { "title": "Websites (domains)", "type": "array", "description": "Find every advertiser that runs ads pointing to these websites, e.g. example.com.", "items": { "type": "string" } }, "startUrls": { "title": "Transparency Center URLs", "type": "array", "description": "Paste adstransparency.google.com URLs (advertiser, ad or website search), or upload a file of them.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxAdvertisersPerQuery": { "title": "Advertisers per name", "minimum": 1, "maximum": 20, "type": "integer", "description": "For advertiser names: how many matching advertiser accounts to scrape (big brands often have several, e.g. one per country). Best match first.", "default": 1 }, "region": { "title": "Region", "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. Also sets the region in the Transparency Center links.", "default": "anywhere" }, "platforms": { "title": "Platforms", "type": "array", "description": "Only ads shown on these Google platforms. Empty = all.", "items": { "type": "string", "enum": [ "SEARCH", "YOUTUBE", "SHOPPING", "MAPS", "PLAY" ], "enumTitles": [ "Google Search", "YouTube", "Google Shopping", "Google Maps", "Google Play" ] } }, "format": { "title": "Ad format", "enum": [ "all", "TEXT", "IMAGE", "VIDEO" ], "type": "string", "description": "Only ads of this format.", "default": "all" }, "dateFrom": { "title": "Shown from", "type": "string", "description": "Only ads shown on or after this date (YYYY-MM-DD). Google's own date filter covers about the last 12 months; for older dates the Actor filters by each ad's first/last shown dates instead." }, "dateTo": { "title": "Shown until", "type": "string", "description": "Only ads shown on or before this date. Defaults to today when only “Shown from” is set." }, "politicalAds": { "title": "Political ads", "type": "boolean", "description": "Search Google's political ads report instead (needs a Region, e.g. US, GB, IN, BR). Political ads include spend and impression ranges. With no advertiser/website given, returns all political ads in the region.", "default": false }, "maxAdsPerTarget": { "title": "Max ads per advertiser / website", "minimum": 0, "maximum": 50000, "type": "integer", "description": "Stop after this many ads for each entry. 0 = all (up to 50,000).", "default": 100 }, "maxAdsTotal": { "title": "Max ads in total", "minimum": 0, "type": "integer", "description": "Stop the whole run after this many ads. 0 = no limit (the run's max cost still applies).", "default": 0 }, "includeDetails": { "title": "Full ad details (extra event)", "type": "boolean", "description": "For every ad also fetch: all variations with their text, landing page URL, YouTube video ID, product title/image (Shopping), regions shown with first/last dates, EU impressions per platform, audience targeting (age, gender, location, interests) and who paid. Charged as an extra ad-details event only when it succeeds.", "default": false }, "includePreviewData": { "title": "Read the rendered ad (landing URL, video, product)", "type": "boolean", "description": "With full details on: also open the ad's rendered preview to get the landing page, YouTube video and Shopping product. Turn off for faster runs if you only need regions/reach/targeting.", "default": true }, "detailConcurrency": { "title": "Detail lookups in parallel", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many ads are enriched at the same time.", "default": 4 }, "includeAdvertiserInfo": { "title": "Advertiser country, legal name & verification", "type": "boolean", "description": "Adds the advertiser's country, legal name and verification status to every ad (one free lookup per advertiser).", "default": true }, "onlyNewAds": { "title": "Only new ads (monitor mode)", "type": "boolean", "description": "Return only ads not seen in earlier runs with the same queries and filters. Use with a schedule to get alerts for new competitor ads. You pay only for new ads.", "default": false }, "monitorStoreName": { "title": "Monitor memory name", "type": "string", "description": "Named key-value store that remembers ads already seen. Use different names for separate monitors.", "default": "ads-transparency-monitor" }, "maxConcurrency": { "title": "Targets in parallel", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many advertisers/websites are scraped at the same time.", "default": 3 }, "maxRetries": { "title": "Max retries per request", "minimum": 0, "maximum": 15, "type": "integer", "description": "Retries (on a new IP) when Google rate-limits or errors.", "default": 6 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "The default Apify datacenter proxy works well; the Actor switches to RESIDENTIAL automatically if Google starts blocking.", "default": { "useApifyProxy": true } }, "fallbackToResidential": { "title": "Fall back to residential proxy", "type": "boolean", "description": "Switch to Apify RESIDENTIAL proxy automatically if Google blocks the datacenter IPs.", "default": true }, "debugLog": { "title": "Debug log", "type": "boolean", "description": "Verbose logging.", "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 } } } } } } } } } }