{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper β€” Ads, Advertisers & Dates", "description": "Scrape the Google Ads Transparency Center: every ad an advertiser or website runs on Search, YouTube, Maps, Play and Shopping, with format, first/last shown dates, days shown, preview image, countries, impressions, targeting and ad text. Advertiser search too. No login.", "version": "0.1", "x-build-id": "kwHydsNNc9AQhAu2l" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/yugenox~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-yugenox-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/yugenox~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-yugenox-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/yugenox~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-yugenox-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": { "advertiserNames": { "title": "πŸ”Ž Advertiser names", "type": "array", "description": "Company or brand names, e.g. \"Nike\", \"Shopify\", \"HubSpot\". Each name is looked up in the Ads Transparency Center's own advertiser search. In \"Ads\" mode the best-matching advertiser (the one whose name is the name you typed, with the most ads) is scraped β€” see \"Which advertisers\" below. In \"Advertisers\" mode every advertiser the search finds is saved as a row.", "items": { "type": "string" } }, "domains": { "title": "🌐 Websites", "type": "array", "description": "Website domains, e.g. \"shopify.com\" or \"https://www.nike.com\". You get the ads that point to that website, from every advertiser β€” exactly what the Transparency Center shows when you search a website.", "items": { "type": "string" } }, "advertiserIds": { "title": "πŸ†” Advertiser IDs", "type": "array", "description": "Advertiser IDs as shown in Transparency Center links, e.g. \"AR16735076323512287233\". Faster and exact β€” no name lookup.", "items": { "type": "string" } }, "startUrls": { "title": "πŸ”— Transparency Center URLs", "type": "array", "description": "Paste links from adstransparency.google.com: an advertiser page (/advertiser/AR…), a single ad (/advertiser/AR…/creative/CR…) or a website search (/?domain=…). The region, format, platform and date filters in the link are kept.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "mode": { "title": "Mode", "enum": [ "ads", "advertisers" ], "type": "string", "description": "\"Ads\" = one row per ad (advertiser, format, first and last shown dates, days shown, preview image, website, links). \"Advertisers\" = one row per advertiser found by name (name, ID, country, verification, number of ads) β€” good for finding who advertises in a niche.", "default": "ads" }, "advertiserMatch": { "title": "Which advertisers (Ads mode)", "enum": [ "best", "all" ], "type": "string", "description": "For advertiser names in \"Ads\" mode: \"Best match\" scrapes the one advertiser whose name is your name (legal suffixes like Inc. or GmbH ignored) with the most ads. \"All matches\" scrapes every advertiser whose name contains all your words (e.g. every country's \"Nike\" entity).", "default": "best" }, "regions": { "title": "🌍 Regions", "type": "array", "description": "Countries where the ads were shown: ISO codes or names, e.g. \"US\", \"GB\", \"Germany\", \"India\". Empty = anywhere. Several countries = ads shown in any of them.", "items": { "type": "string" } }, "format": { "title": "Ad format", "enum": [ "ALL", "TEXT", "IMAGE", "VIDEO" ], "type": "string", "description": "Text (Search), image (Display / Shopping) or video (YouTube) ads only. \"All\" = every format.", "default": "ALL" }, "platforms": { "title": "Platforms", "type": "array", "description": "Google platforms the ads ran on. Empty = all.", "items": { "type": "string", "enum": [ "SEARCH", "YOUTUBE", "MAPS", "PLAY", "SHOPPING" ], "enumTitles": [ "Google Search", "YouTube", "Google Maps", "Google Play", "Google Shopping" ] } }, "dateFrom": { "title": "Shown from", "type": "string", "description": "Only ads shown on or after this date (YYYY-MM-DD, or relative like \"30 days\"). Empty = no limit." }, "dateTo": { "title": "Shown until", "type": "string", "description": "Only ads shown on or before this date (YYYY-MM-DD, or relative like \"7 days\"). Empty = up to today." }, "maxAdsPerTarget": { "title": "Max ads per advertiser / website", "minimum": 0, "maximum": 50000, "type": "integer", "description": "Most ads to save for each advertiser, website or URL (newest first, the Transparency Center's own order). With \"Only new ads\": how many of the newest ads are re-checked each run. In \"Advertisers\" mode: most advertisers per name searched. 0 = all of them (up to Max rows).", "default": 100 }, "maxItems": { "title": "Max rows", "minimum": 0, "maximum": 50000, "type": "integer", "description": "Most rows for the whole run. 0 = no limit (50,000 per run at most).", "default": 1000 }, "includeAdDetails": { "title": "Include ad details", "type": "boolean", "description": "Also read each ad's detail page: every country it was shown in (first and last date, impressions range, platforms), Google Search / YouTube / Maps / Play / Shopping, audience targeting used (age, gender, location, topics, customer lists), who paid for it, every variation, and the ad's content β€” headline and text, image URLs, YouTube video. Charged as an extra \"ad details\" event per ad (see Pricing); takes a few more seconds per 10 ads.", "default": false }, "onlyNew": { "title": "Only new ads (monitor mode)", "type": "boolean", "description": "Skip ads (or advertisers) that an earlier run with the same input already saved β€” they are not saved and not charged as ads. Each run re-checks the newest ads of every advertiser / website, up to \"Max ads per advertiser / website\", and saves only the ones you don't have yet. Schedule the run daily or weekly to get each competitor's new ads.", "default": false }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify Proxy (datacenter) is the default and comes with every Apify plan, including the free one.", "default": { "useApifyProxy": true } }, "_noResidential": { "title": "Run as an account without residential proxies", "type": "boolean", "description": "Internal (canaries): behave exactly like an account without the RESIDENTIAL proxy group.", "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 } } } } } } } } } }