{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper & API: Competitor Ads", "description": "Competitor domains in, Google ad intelligence out: every creative with first-shown and last-shown dates, a report on what they just launched and what has run long enough to be working, which affiliates bid on their domain, and a feed of ads launched, stopped or resumed since your last run.", "version": "0.1", "x-build-id": "co4jw5BaDgwpTqISD" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/friendlyapi~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-friendlyapi-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/friendlyapi~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-friendlyapi-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/friendlyapi~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-friendlyapi-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": [ "mode", "domains" ], "properties": { "mode": { "title": "Mode", "enum": [ "ad_report", "fetch_ads", "who_advertises", "watch_changes" ], "type": "string", "description": "ad_report = the answer: how much a competitor is advertising, what they just launched, what works; fetch_ads = every creative as rows; who_advertises = who is running ads to a domain (catches affiliates bidding on your brand); watch_changes = only what launched, stopped or resumed since the last run", "default": "ad_report" }, "domains": { "title": "Competitor domains", "type": "array", "description": "One entry per competitor: the destination domain you want to see advertising for, e.g. \"hubspot.com\". Full URLs are fine. Up to 200 for reports and ads, 500 for watching. Note that a domain is not an advertiser: several parties often run ads to the same domain, and the output names all of them. Very large advertisers (thousands of creatives) take longer, so start with a couple." }, "watch_id": { "title": "Watch ID (watch_changes mode)", "type": "string", "description": "Stable name for this competitor set, e.g. 'my-competitors'. It names the stored snapshot the next run diffs against. The first run with a new watch_id sets the baseline and emits no events; schedule the actor and later runs emit only real changes." }, "max_ads_per_domain": { "title": "Max creatives per domain", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Cap per domain in fetch_ads mode. Large advertisers list hundreds.", "default": 1000 }, "running_only": { "title": "Only currently running creatives", "type": "boolean", "description": "Skip creatives that Google has not served in the last 2 days. Useful for 'what are they running right now'; leave off to see the full history including what they retired.", "default": false }, "proxy": { "title": "Proxy", "type": "object", "description": "Google's Ads Transparency Center rate-limits hard by IP address and does not forgive quickly, so this actor rotates a fresh proxy session per request. Leave the default on. Running without a proxy works for a single small domain and will be throttled beyond that.", "default": { "useApifyProxy": true } }, "proxy_country": { "title": "Measure from this country", "type": "string", "description": "Two-letter country code for the proxy exit, default US. This is not cosmetic: Google localises the Transparency Center by caller country, so the region counts and the creative set depend on where you appear to be. Keep it CONSTANT between watch runs, or the change feed will report differences that are only your own vantage point moving.", "default": "US" }, "region_code": { "title": "Region code (advanced)", "type": "integer", "description": "Google's internal region selector for the Transparency Center. The default (2586) is the documented value and returns worldwide results. Only change this if you know the code you want; we do not publish a guessed mapping, because a wrong one would silently narrow your results.", "default": 2586 } } }, "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 } } } } } } } } } }