{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper - Competitor Ad Library", "description": "Scrape every ad a company runs on Google Search, YouTube, Shopping, Maps and Play from the public Ads Transparency Center. Search by domain, brand name or advertiser ID. Get creative previews, first and last shown dates and days running. No login.", "version": "0.1", "x-build-id": "zOGvRHAd6uBu2Lhve" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cirkit~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cirkit-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/cirkit~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-cirkit-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/cirkit~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-cirkit-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": "Website domains the ads link to, for example nike.com. This is the most reliable way to find a company's ads because it catches every advertiser account the company uses. Scheme, www and paths are stripped for you.", "items": { "type": "string" } }, "advertiserNames": { "title": "Advertiser names", "type": "array", "description": "Brand names to look up in the Transparency Center's own advertiser directory, for example Nike. Matching is a prefix match on the advertiser's registered legal name, so a domain works better when you know it.", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Transparency Center advertiser IDs, which start with AR and appear in the advertiser page URL, for example AR16735076323512287233.", "items": { "type": "string" } }, "startUrls": { "title": "Transparency Center URLs", "type": "array", "description": "Advertiser or domain-search URLs copied straight from adstransparency.google.com. The advertiser ID, the domain and the region are read out of each URL.", "items": { "type": "string" } }, "resultType": { "title": "What to return", "enum": [ "ads", "advertisers" ], "type": "string", "description": "ads returns one row per ad creative. advertisers returns one summary row per matching advertiser with Google's approximate ad count, which is the cheap way to check whether a list of companies runs Google Ads at all. advertisers only reads the Advertiser names field.", "default": "ads" }, "region": { "title": "Region", "enum": [ "US", "GB", "CA", "AU", "DE", "FR", "ES", "IT", "NL", "SE", "NO", "DK", "FI", "IE", "PL", "PT", "AT", "BE", "CH", "CZ", "GR", "HU", "RO", "BG", "HR", "SI", "SK", "EE", "LV", "LT", "RS", "UA", "TR", "IN", "JP", "KR", "SG", "HK", "TW", "MY", "TH", "VN", "ID", "PH", "NZ", "BR", "MX", "AR", "CL", "CO", "PE", "ZA", "NG", "EG", "IL", "AE", "SA", "MA" ], "type": "string", "description": "Two-letter country code for the country the ads were shown in. The Transparency Center is region-scoped, so the same advertiser returns a different set of ads in every country.", "default": "US" }, "adFormat": { "title": "Ad format", "enum": [ "ANY", "IMAGE", "TEXT", "VIDEO" ], "type": "string", "description": "Keep only one format. TEXT covers Search and Shopping ads and is the format that carries ad copy. IMAGE covers display banners. VIDEO covers YouTube ads.", "default": "ANY" }, "platforms": { "title": "Google surfaces", "type": "array", "description": "Keep only ads served on these Google surfaces. Leave empty for all of them. Google only records the surface for ads shown on or after 2023-09-04, so any selection here hides everything older.", "items": { "type": "string", "enum": [ "GOOGLE_SEARCH", "YOUTUBE", "GOOGLE_SHOPPING", "GOOGLE_MAPS", "GOOGLE_PLAY" ], "enumTitles": [ "Google Search", "YouTube", "Google Shopping", "Google Maps", "Google Play" ] }, "default": [] }, "maxItems": { "title": "Maximum ads", "minimum": 0, "type": "integer", "description": "Stop after this many rows across all targets. Set 0 for everything the Transparency Center will serve, which for a large advertiser can be tens of thousands of ads.", "default": 200 }, "extractAdCopy": { "title": "Extract ad copy", "type": "boolean", "description": "Fetch each ad's rendered preview and read the headline out of it. Only text, video and rich-media ads have a preview to read, and the headline comes back on roughly half of those, so expect nulls elsewhere. Adds about 1.5 seconds per ad.", "default": false }, "includeVariations": { "title": "Include A/B variations", "type": "boolean", "description": "Fetch every A/B variation Google holds for each ad and attach them to the row. Adds one request per ad.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Google rate-limits by IP, so the actor rotates the exit node whenever it is throttled. The Apify datacenter pool is enough; residential proxies are not needed for this target.", "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 } } } } } } } } } }