{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper - Competitor Ads Library", "description": "See competitor Google Ads: every creative Google's own Ads Transparency Center lists for an advertiser - format, preview, first and last shown dates, days active and the countries it ran in. Only-new-creatives alerts turn a schedule into a competitor-ad feed.", "version": "0.1", "x-build-id": "TUzwbbFpPp7D8CftN" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/flash_scraper~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-flash_scraper-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/flash_scraper~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-flash_scraper-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/flash_scraper~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-flash_scraper-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": "Domains or brand terms", "type": "array", "description": "One per line: a domain like 'nike.com' (exact) or a brand term like 'nike' (auto-resolved to the top matching advertiser domain). Supplying your own list replaces the sample entirely. Note: a list that byte-equals the sample (['nike.com']) sent ALONGSIDE advertiserIds is read as the injected schema default and dropped - the run's status message says so; re-enter it as 'www.nike.com' or add a second entry to keep it.", "default": [ "nike.com" ], "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Google advertiser IDs starting with 'AR' (every delivered row carries its advertiser_id, so grab them from a first run and watch specific advertisers precisely). A pasted Transparency Center URL works too - the AR... id is extracted. Entries with no AR... id are rejected and named in the status message; if none of the ids you give is usable the run delivers 0 rows and charges nothing, it never falls back to the sample domain.", "default": [], "items": { "type": "string" } }, "format": { "title": "Ad format", "enum": [ "any", "text", "image", "video" ], "type": "string", "description": "Only keep ads of one format. 'any' keeps everything.", "default": "any" }, "activeWithinDays": { "title": "Active within days", "minimum": 0, "maximum": 3650, "type": "integer", "description": "Only keep ads LAST SHOWN within the last N days - the honest way to see a competitor's currently running campaigns instead of a year of history. 0 = no filter (the Console form starts at 30). Ads whose last-shown date Google doesn't state are kept, never guessed away.", "default": 0 }, "region": { "title": "Region (country code)", "type": "string", "description": "Two-letter ISO 3166-1 country code (US, FR, GB, DE, MA, TW...). Keeps only ads with a published per-country record for that country - checked against each ad's own detail record (one paced request per checked ad, so filtered runs take longer). The check inspects at most 1000 candidates per run and stops as soon as maxItems ads have matched. A code that is not a real ISO country stops the run with 0 rows and no charge instead of quietly delivering a worldwide pull. Empty = worldwide.", "default": "" }, "onlyNewCreatives": { "title": "Only new creatives since the last run", "type": "boolean", "description": "The first run is the baseline (delivers everything and says so). Every later run with the same targets + filters (format, activeWithinDays, region - each watch keeps its own memory) delivers ONLY creatives not seen before; a run where nothing is new delivers nothing, bills nothing, and says 'Nothing new' plainly. Creatives that are still running have their timestamp refreshed every run, so a long-lived ad is never forgotten and re-alerted. Memory lives in a named key-value store ('google-ads-monitor') in your own account.", "default": false }, "maxItems": { "title": "Max ads", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Total cap across ALL targets in the run, split round-robin so one giant advertiser cannot eat the whole budget. Your cost ceiling. Default 100; the Console form starts at 50.", "default": 100 }, "includeDetails": { "title": "Fetch per-country records", "type": "boolean", "description": "Fetch each delivered ad's detail record and fill the regions, region_stats, impressions_min and impressions_max columns - the countries where the ad ran and Google's published EU impression ranges. region_stats carries Google's per-country published range; the top-level impressions_min/impressions_max are the SUM of those per-country bounds across all countries the ad ran in, not a single published range. One extra paced request per delivered ad. (Automatically on when Region is set.)", "default": false }, "proxy": { "title": "Proxy", "type": "object", "description": "Google rate-limits this endpoint per IP (measured: ~15 rapid requests earn a 429), so the default Apify Proxy with automatic fresh-session rotation is recommended. Your own proxy URLs are honored.", "default": { "useApifyProxy": 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 } } }, "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 } } } } } } } } } }