{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper: Ad Library API", "description": "Every ad a company runs on Google Search, YouTube, Shopping, Maps and Play from the Google Ads Transparency Center: ad copy, images, videos, first and last shown dates, EU impressions and audience targeting, plus a daily new-ads watcher. Search by advertiser name, domain or ID; no login.", "version": "0.1", "x-build-id": "MImkk0esLpPaThOdL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/varnmill~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-varnmill-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/varnmill~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-varnmill-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/varnmill~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-varnmill-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": [ "searches" ], "properties": { "searches": { "title": "Advertisers, domains, IDs or URLs", "type": "array", "description": "What to look up. Each line is one of: an advertiser name as Google shows it (e.g. 'Nike, Inc.' or just 'Nike'), a website domain (e.g. 'nike.com' — returns every ad that points to it, from any advertiser), an advertiser ID (AR followed by digits), or an Ads Transparency Center URL of an advertiser, a domain search or a single ad.", "items": { "type": "string" } }, "mode": { "title": "Mode", "enum": [ "ads", "advertisers" ], "type": "string", "description": "'ads' returns one row per ad. 'advertisers' returns advertiser rows instead: for a name, every advertiser Google suggests with its ad count; for a domain, every advertiser running ads that point to it, with how many ads each.", "default": "ads" }, "region": { "title": "Region", "enum": [ "anywhere", "AF", "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", "CV", "KH", "CM", "CA", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "HR", "CU", "CW", "CY", "CZ", "CI", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "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", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RO", "RU", "RW", "RE", "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", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TM", "TC", "TV", "TR", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW", "AX" ], "type": "string", "description": "Only ads shown in this country. 'Anywhere' covers all countries. Impressions and audience data exist only for ads shown in the EU (Google publishes them under the Digital Services Act).", "default": "anywhere" }, "platform": { "title": "Platform", "enum": [ "any", "SEARCH", "YOUTUBE", "SHOPPING", "MAPS", "PLAY" ], "type": "string", "description": "Only ads shown on this Google product.", "default": "any" }, "adFormat": { "title": "Ad format", "enum": [ "any", "TEXT", "IMAGE", "VIDEO" ], "type": "string", "description": "Only ads of this format.", "default": "any" }, "lastDays": { "title": "Shown in the last N days", "minimum": 0, "type": "integer", "description": "Only ads shown at least once in the last N days (1 = today). 0 turns this off. Overrides the start and end dates.", "default": 0 }, "startDate": { "title": "Shown on or after", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only ads shown at least once between this date and the end date, as YYYY-MM-DD. Leave empty for no date filter." }, "endDate": { "title": "Shown on or before", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "End of the date window, as YYYY-MM-DD. Defaults to today when only a start date is set." }, "maxAdsPerSearch": { "title": "Max ads per input", "minimum": 1, "type": "integer", "description": "How many ads to read for each line in 'searches' (most recently shown first). Big brands run tens of thousands of ads, so set this to what you need. In advertisers mode with a domain, this is how many ads are scanned to find advertisers.", "default": 100 }, "includeAdContent": { "title": "Ad copy, images and videos", "type": "boolean", "description": "Read each ad's preview to get the headline, description, display URL, call to action, image URLs and YouTube video ID. One extra request per ad, no extra charge.", "default": true }, "includeDetails": { "title": "Per-country stats, impressions and targeting (add-on)", "type": "boolean", "description": "Add the countries each ad ran in with first and last shown dates per country, impressions ranges per country and per platform (ads shown in the EU), audience selection (demographics, locations, contextual signals...) and every variation of the ad's copy. Charged as an extra 'ad-details' event per ad.", "default": false }, "allAdvertiserMatches": { "title": "Use every advertiser with the same name", "type": "boolean", "description": "When you enter a name, Google often has several advertisers with it (e.g. one per country). Off: only the one with the most ads. On: all of them.", "default": false }, "onlyNew": { "title": "Only ads not seen before (watcher)", "type": "boolean", "description": "Remember every ad returned under the watcher name and output only ads that earlier runs did not return. Schedule the actor daily with 'Shown in the last N days' set to 2 or 3 to get new competitor ads as they launch. Skipped ads are not charged.", "default": false }, "watcherName": { "title": "Watcher name", "type": "string", "description": "Name of the watcher memory (kept in the named key-value store 'google-ads-transparency-state'). Use a different name for each scheduled task so they do not share memory.", "default": "default" }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "Requests in flight at once. Higher is faster but more likely to be rate limited.", "default": 5 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Not needed normally. Requests go straight from the Apify server and switch to an Apify datacenter proxy automatically if Google rate limits them.", "default": { "useApifyProxy": false } }, "autoProxyFallback": { "title": "Switch to a proxy when rate limited", "type": "boolean", "description": "If Google keeps answering 'too many requests', retry through the Apify datacenter proxy.", "default": true } } }, "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 } } } } } } } } } }