{ "openapi": "3.0.1", "info": { "title": "Google Ads Scraper — Ads Transparency by Domain or Advertiser", "description": "Google Ads scraper for competitor research: every Search, YouTube, Display and Shopping ad a domain or advertiser runs, read from the public Google Ads Transparency Center. Format, first/last shown, regions, impressions, ad copy, images, video. $0.60 per 1,000 ads.", "version": "0.1", "x-build-id": "ZbKQeQyorJKgto7Ob" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/actor-forge~google-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-actor-forge-google-ads-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/actor-forge~google-ads-scraper/runs": { "post": { "operationId": "runs-sync-actor-forge-google-ads-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/actor-forge~google-ads-scraper/run-sync": { "post": { "operationId": "run-sync-actor-forge-google-ads-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": "Advertiser websites (domains)", "type": "array", "description": "Competitor websites, e.g. nike.com. Returns the ads Google lists for that domain in the Ads Transparency Center (Search, YouTube, Display and Shopping), from the brand itself and from agencies or resellers advertising it.", "items": { "type": "string" } }, "advertiserNames": { "title": "Advertiser names", "type": "array", "description": "Company names as shown in the Ads Transparency Center, e.g. HubSpot, Argos Limited. Exact name matches are used (a brand's several legal entities are all kept); otherwise the closest advertiser with the most ads.", "default": [], "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Google advertiser IDs (AR… from an adstransparency.google.com/advertiser/AR… link).", "default": [], "items": { "type": "string" } }, "regions": { "title": "Regions (country codes)", "type": "array", "description": "Only ads shown in these countries, as two-letter codes (US, GB, DE, FR…). Empty = anywhere.", "default": [], "items": { "type": "string" } }, "dateFrom": { "title": "Shown from (date)", "type": "string", "description": "Only ads shown on or after this date (YYYY-MM-DD)." }, "dateTo": { "title": "Shown until (date)", "type": "string", "description": "Only ads shown on or before this date (YYYY-MM-DD)." }, "formats": { "title": "Ad formats", "type": "array", "description": "Only these formats. Empty = all formats (text covers Search ads; image and video cover Display, YouTube and Shopping creatives).", "items": { "type": "string", "enum": [ "text", "image", "video" ], "enumTitles": [ "Text", "Image", "Video" ] }, "default": [] }, "maxAdsPerAdvertiser": { "title": "Max ads per domain / advertiser", "minimum": 1, "maximum": 10000, "type": "integer", "description": "How many ads to read for each domain, advertiser name or advertiser ID, newest first as the Transparency Center lists them.", "default": 100 }, "maxResults": { "title": "Max ads in total", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Stop after this many ads across all searches. You pay per ad delivered ($0.60 per 1,000).", "default": 1000 }, "includeDetails": { "title": "Include ad details (regions, impressions, ad copy)", "type": "boolean", "description": "One extra lookup per ad: countries shown, impression ranges and first/last shown per country, plus best-effort headline/description text. Charged as ad-detail ($1 per 1,000).", "default": false }, "onlyNewSinceLastRun": { "title": "Only new ads since the last run (monitoring)", "type": "boolean", "description": "Remember every ad delivered in a named key-value store (ads-seen-) and return only ads not seen before. Schedule the actor daily to get a feed of competitors' new ads; already-seen ads are skipped and never charged.", "default": false }, "monitorName": { "title": "Monitor name", "maxLength": 48, "type": "string", "description": "Name of the seen-ads memory used by 'Only new ads'. Use one name per schedule (e.g. uk-competitors) so separate watch lists don't share state.", "default": "default" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Not needed: the Transparency Center is public. Leave off unless you have your own reason to route requests through a proxy. The actor never rotates proxies to get around a block.", "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 } } } } } } } } } }