{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper: Competitor Ads & EU Reach", "description": "Scrape the Google Ads Transparency Center by domain, advertiser ID or name. Get every ad with advertiser, verified status, format, dates, regions and creative links, plus optional EU impressions, targeting and video files. New-ads monitoring. No login.", "version": "1.1", "x-build-id": "o5WMHeCbsEVUreQ6c" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/hydrocore~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-hydrocore-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/hydrocore~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-hydrocore-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/hydrocore~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-hydrocore-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": { "domains": { "title": "Domains", "type": "array", "description": "Websites whose ads you want, for example nike.com. You get ads from every advertiser account that points to that site (the brand itself, resellers and agencies). Full links are fine; we keep only the domain.", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Google advertiser IDs (they start with AR, like AR16735076323512287233) or links to an advertiser page on adstransparency.google.com. Use this when you want exactly one company's ads.", "items": { "type": "string" } }, "advertiserNames": { "title": "Advertiser names", "type": "array", "description": "Company names to look up, for example Decathlon. The Actor uses the Transparency Center's own name search and scrapes the best match(es).", "items": { "type": "string" } }, "maxAdvertisersPerName": { "title": "Advertisers per name", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many matching advertiser accounts to scrape for each name. Exact name matches come first, then the accounts with the most ads.", "default": 1 }, "regions": { "title": "Regions", "type": "array", "description": "Only ads shown in these places. Use 2-letter country codes (US, GB, DE, FR...), EU for all 27 EU countries, or anywhere (default) for the whole world. Several codes = ads shown in any of them.", "items": { "type": "string" } }, "dateFrom": { "title": "Shown on or after", "type": "string", "description": "Only ads that were running on or after this date (YYYY-MM-DD). Leave empty for no limit." }, "dateTo": { "title": "Shown on or before", "type": "string", "description": "Only ads that were running on or before this date (YYYY-MM-DD). Leave empty for today." }, "lastDays": { "title": "Or: shown in the last N days", "minimum": 0, "maximum": 3650, "type": "integer", "description": "Shortcut for a moving window, handy for scheduled runs: 30 = ads that ran at some point in the last 30 days. Overrides the two dates above. 0 or empty = off." }, "format": { "title": "Ad format", "enum": [ "all", "text", "image", "video" ], "type": "string", "description": "Google's own format label for the ad.", "default": "all" }, "platform": { "title": "Platform", "enum": [ "all", "search", "youtube", "shopping", "maps", "play" ], "type": "string", "description": "Only ads shown on this Google platform.", "default": "all" }, "sortBy": { "title": "Sort ads by", "enum": [ "lastShown", "firstShownNewest", "firstShownOldest", "longestRunning" ], "type": "string", "description": "Order of the saved ads for each domain / advertiser. Default is Google's own order (last shown, newest first). Other orders are applied before the limit below: the Actor lists up to max(500, 5 × the limit) ads (at most 2,000) for free, sorts them, then saves the top ads. Listing more pages takes a little longer.", "default": "lastShown" }, "maxAdsPerSource": { "title": "Max ads per domain / advertiser", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Stop after this many ads for each domain, advertiser ID or advertiser name. Big brands run tens of thousands of ads, so start small.", "default": 100 }, "maxAdsTotal": { "title": "Max ads in total", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Optional overall limit for the whole run. 0 or empty = no overall limit." }, "includeDetails": { "title": "Ad details (reach, countries, audience)", "type": "boolean", "description": "Also open each ad's detail page: every country where it ran with first/last shown dates, the topic, all creative variations, video links and ad text where Google's preview has it, and for EU ads Google's impression ranges per country and per platform plus the audience selection (demographics, locations, contextual signals, customer lists). Costs an extra 'Ad details' event per ad and is slower.", "default": false }, "includeAdvertiserInfo": { "title": "Advertiser verification and country", "type": "boolean", "description": "Look up each advertiser once to add whether Google verified its identity and its registered country. Free (no extra charge).", "default": true }, "onlyNewAds": { "title": "Only new ads since the last run (monitoring)", "type": "boolean", "description": "Remember the ads already delivered for this exact search and save only ads you have not received before. The first run saves everything it finds (your starting list). Schedule the Actor to get a feed of new competitor ads. Memory is kept in your account's key-value store google-ads-transparency-monitor.", "default": false }, "monitorKey": { "title": "Monitoring list name", "type": "string", "description": "Optional. By default the memory is tied to the exact domains, IDs, names, regions, format and platform. Set a name (for example competitors-eu) to keep the same memory even if you edit the search." }, "maxSpendUsd": { "title": "Max spend for this run (USD)", "type": "string", "description": "Optional, for example 1.50. The run stops before going over it. Apify's own \"Maximum cost per run\" option is respected too; the lower of the two applies. Leave empty for no extra limit." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Not needed for normal use. If Google shows its \"unusual traffic\" page to the server (the run then stops early with a clear message), enable Apify Proxy and the Actor switches to a fresh IP instead of waiting. Proxy traffic is billed by Apify to your account.", "default": { "useApifyProxy": false } } } }, "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 } } } } } } } } } }