{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency — Search/YouTube/Display Ad Spy", "description": "Scrape Google's public Ad Transparency Center — every Google Search, YouTube and Display ad an advertiser runs. Search by keyword or advertiser ID. Get creative HTML, image/video URLs, dates, formats, variants. Pure HTTP, no Chromium. DSA-mandated public data.", "version": "1.0", "x-build-id": "vMRitMCDwj069WIEK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dltik~google-ads-transparency/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dltik-google-ads-transparency", "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/dltik~google-ads-transparency/runs": { "post": { "operationId": "runs-sync-dltik-google-ads-transparency", "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/dltik~google-ads-transparency/run-sync": { "post": { "operationId": "run-sync-dltik-google-ads-transparency", "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": { "searchQuery": { "title": "Search query", "type": "string", "description": "Single search query — paste an advertiser name (e.g. 'Nike') or an advertiser ID (e.g. 'AR02981058906626719745'). Strings starting with 'AR' are treated as direct IDs; everything else is resolved via the autocomplete to the top matching advertisers." }, "queries": { "title": "Search keywords (bulk)", "type": "array", "description": "Advanced: multiple brand/advertiser names at once. Use this OR searchQuery, not both. Example: ['Nike','Adidas'].", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Advertiser IDs from the Ad Transparency Center (e.g. 'AR02981058906626719745'). Skips the keyword lookup and fetches creatives directly. Find them in the URL on adstransparency.google.com.", "items": { "type": "string" } }, "region": { "title": "Region", "type": "string", "description": "ISO country code to filter ads by where they were shown (US, FR, GB, DE, IT, ES, CA, JP, AU, BR, MX, NL). Use 'ANYWHERE' for any region.", "default": "US" }, "regionId": { "title": "Region (numeric override)", "minimum": 0, "type": "integer", "description": "Advanced: Google's internal region ID (e.g. 2250 = US, 2012 = FR). Overrides the ISO mapping above when set — use this for regions the ISO mapping doesn't know yet." }, "platforms": { "title": "Platforms (string aliases — best-guess mapping)", "type": "array", "description": "Filter by Google platforms. Note: the string → numeric mapping is reverse-engineered and may need fixes — if the results don't match the platform you expect, use the numeric platformIds override below instead.", "items": { "type": "string", "enum": [ "google_search", "youtube", "google_shopping", "google_maps", "google_play" ], "enumTitles": [ "Google Search", "YouTube", "Google Shopping", "Google Maps", "Google Play" ] } }, "platformIds": { "title": "Platform IDs (numeric override)", "type": "array", "description": "Advanced: bypass the string mapping and pass Google's internal platform integers directly (subset of [1,2,3,4,5]). Read them off the Ad Transparency Center URL when you apply a platform filter in the UI.", "items": { "type": "integer" } }, "format": { "title": "Creative format", "enum": [ "any", "text", "image", "video" ], "type": "string", "description": "Only return ads of this creative format.", "default": "any" }, "dateFrom": { "title": "Date from", "type": "string", "description": "Only return ads shown on or after this date (YYYY-MM-DD). Leave empty for no lower bound." }, "dateTo": { "title": "Date to", "type": "string", "description": "Only return ads shown on or before this date (YYYY-MM-DD). Leave empty for no upper bound." }, "topAdvertisersPerQuery": { "title": "Top advertisers per keyword", "minimum": 1, "maximum": 10, "type": "integer", "description": "When searching by keyword, how many top matching advertisers to scrape per query (autocomplete returns ~10).", "default": 3 }, "maxResultsPerAdvertiser": { "title": "Max creatives per advertiser", "minimum": 1, "maximum": 100, "type": "integer", "description": "Cap on creatives per advertiser. Google's API caps at 100 per request and the public cursor isn't exposed, so values above 100 are treated as 100. For broader coverage of large advertisers, run separate queries per region.", "default": 50 }, "useResidentialProxy": { "title": "Use residential proxy (optional)", "type": "boolean", "description": "Enable only if Google rate-limits your runs — the Ad Transparency Center API works fine from Apify datacenter IPs (free, no rate limit observed). Residential rotation is available as a fallback for high-volume runs.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Advanced: override the proxy. Only honored when 'Use residential proxy' is enabled. Defaults to Apify residential when proxy is on.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } }, "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 } } } } } } } } } }