{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Center Scraper", "description": "Every Google ad a brand or domain runs on Search, YouTube, Shopping, Maps and Play: format, first/last shown, days running, image/preview/YouTube links, plus optional per-country impressions and platform breakdown. Monitor mode for new ads.", "version": "1.0", "x-build-id": "7eO7wq0KL7spbnfaV" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/clearscrape~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-clearscrape-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/clearscrape~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-clearscrape-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/clearscrape~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-clearscrape-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": "Search queries", "type": "array", "description": "Brand names (e.g. 'Canva'), domains (e.g. 'nike.com'), advertiser IDs (AR...) or Transparency Center URLs. The type is detected automatically. Brand names are matched to the closest advertisers (see 'Advertisers per brand query').", "items": { "type": "string" } }, "domains": { "title": "Domains", "type": "array", "description": "Advertiser website domains, e.g. 'shopify.com'. Returns every ad that points to this domain, from all advertisers.", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Google advertiser IDs (start with AR), taken from a Transparency Center URL such as adstransparency.google.com/advertiser/AR0637...", "items": { "type": "string" } }, "startUrls": { "title": "Transparency Center URLs", "type": "array", "description": "Advertiser, domain or single-creative URLs copied from adstransparency.google.com. A 'region' parameter in the URL is respected.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "resultType": { "title": "What to return", "enum": [ "ads", "advertisers" ], "type": "string", "description": "'ads' returns ad creatives. 'advertisers' only looks up brand queries and returns matching advertiser records (ID, legal name, country, verified flag, ad count range).", "default": "ads" }, "region": { "title": "Region", "type": "string", "description": "2-letter country code where the ads were shown (US, AU, GB, DE, ...), or 'anywhere'.", "default": "anywhere" }, "platforms": { "title": "Platforms", "type": "array", "description": "Only ads shown on these Google surfaces. Leave empty for all.", "items": { "type": "string", "enum": [ "SEARCH", "YOUTUBE", "MAPS", "PLAY", "SHOPPING" ], "enumTitles": [ "Google Search", "YouTube", "Google Maps", "Google Play", "Google Shopping" ] } }, "adFormat": { "title": "Ad format", "enum": [ "ALL", "TEXT", "IMAGE", "VIDEO" ], "type": "string", "description": "Only ads of this format. Note: Google renders most text ads as images in the Transparency Center.", "default": "ALL" }, "startDate": { "title": "Shown on or after", "type": "string", "description": "Only ads shown at some point in this window (YYYY-MM-DD)." }, "endDate": { "title": "Shown on or before", "type": "string", "description": "End of the window (YYYY-MM-DD)." }, "maxAdsPerSearch": { "title": "Max ads per search", "minimum": 0, "type": "integer", "description": "Maximum ads per query / domain / advertiser. 0 = no limit (big brands have tens of thousands of ads).", "default": 100 }, "maxResults": { "title": "Max results in total", "minimum": 0, "type": "integer", "description": "Hard cap across the whole run. 0 = no cap. Your 'Maximum cost per run' is always respected too.", "default": 0 }, "maxAdvertisersPerQuery": { "title": "Advertisers per brand query", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many matching advertisers to include for each brand-name query (best match first). Domains and IDs are exact and ignore this.", "default": 3 }, "includeDetails": { "title": "Include regions, impressions & variations", "type": "boolean", "description": "One extra lookup per ad: every country the ad ran in with first/last dates, impression ranges, per-platform impressions, total impressions and all creative variations. Video ads also get their YouTube link. Charged as a separate 'ad details' event.", "default": false }, "extractVideoUrls": { "title": "Extract YouTube links for video ads", "type": "boolean", "description": "With details on, read the video preview to get the YouTube video ID and URL.", "default": true }, "onlyNewAds": { "title": "Only new ads (monitoring)", "type": "boolean", "description": "Remember ads seen in earlier runs and return only ones not seen before. Schedule the Actor daily to get a feed of new competitor ads.", "default": false }, "monitorStoreName": { "title": "Monitor store name", "type": "string", "description": "Named key-value store that keeps the seen ads. Use a different name per monitoring project.", "default": "ads-transparency-monitor" }, "includeRawData": { "title": "Include raw data", "type": "boolean", "description": "Attach the raw Transparency Center record to each item (for debugging).", "default": false }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Google limits requests per IP. Apify datacenter proxy is enough for most runs; residential is the safest for very large runs.", "default": { "useApifyProxy": true } }, "residentialFallback": { "title": "Switch to residential proxy if blocked", "type": "boolean", "description": "After repeated blocks, finish the run on Apify residential proxy (uses your residential proxy traffic).", "default": true }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many searches/lookups run in parallel. Keep low (2-4) unless you use residential proxy.", "default": 3 }, "maxRetries": { "title": "Max retries per request", "minimum": 0, "maximum": 10, "type": "integer", "description": "Retries per request; each retry rotates the proxy session.", "default": 5 }, "requestDelayMs": { "title": "Delay between requests (ms)", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Politeness delay after each request.", "default": 250 }, "pageSize": { "title": "Page size", "minimum": 10, "maximum": 100, "type": "integer", "description": "Ads requested per page (10-100).", "default": 40 } } }, "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 } } } } } } } } } }