{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper & Ad Monitor", "description": "Scrape Google Ads Transparency Center ads by domain, advertiser or URL. Monitor competitors: get new, reactivated and ended ads since the last run.", "version": "0.1", "x-build-id": "zs8or5HyHV4uXUZqN" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cylindrical_lighthouse~google-ads-transparency/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cylindrical_lighthouse-google-ads-transparency", "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/cylindrical_lighthouse~google-ads-transparency/runs": { "post": { "operationId": "runs-sync-cylindrical_lighthouse-google-ads-transparency", "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/cylindrical_lighthouse~google-ads-transparency/run-sync": { "post": { "operationId": "run-sync-cylindrical_lighthouse-google-ads-transparency", "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": { "mode": { "title": "Mode", "enum": [ "scrape", "monitor" ], "type": "string", "description": "'scrape' returns every matching ad (up to the per-query limit). 'monitor' compares with the previous run of the same query and returns only changes: ads that are new, reactivated or ended. The first monitor run returns the current ads as a 'baseline'. Example: \"monitor\" for a weekly competitor-ads report.", "default": "scrape" }, "domains": { "title": "Advertiser website domains", "type": "array", "description": "Website domains whose Google ads you want, one per line. Returns ads from every advertiser account that points to this domain. Protocol, 'www.' and paths are stripped automatically. If you give no domain, name, ID or URL at all, the example 'nike.com' is used. Example: \"nike.com\".", "items": { "type": "string" } }, "advertiserNames": { "title": "Advertiser names", "type": "array", "description": "Company or brand names, one per line. Each name is resolved to the matching verified advertiser account(s) with the most ads. Use 'Advertisers per name' to pull more than one account. Example: \"HelloFresh\".", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Google advertiser IDs: 'AR' followed by 20 digits, as shown in a Transparency Center advertiser URL. Example: \"AR16735076323512287233\" (Nike, Inc.).", "items": { "type": "string" } }, "startUrls": { "title": "Transparency Center URLs", "type": "array", "description": "Paste advertiser, creative or domain-search URLs copied from adstransparency.google.com. The advertiser ID or domain is extracted automatically. Example: \"https://adstransparency.google.com/advertiser/AR16735076323512287233?region=US\".", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "region": { "title": "Region", "enum": [ "anywhere", "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CX", "CC", "CO", "KM", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "CD", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IQ", "IE", "IR", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "KP", "MP", "NO", "OM", "PK", "PW", "PA", "PG", "PY", "CN", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "GM", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "PS", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TH", "MK", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "TZ", "UM", "US", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW" ], "type": "string", "description": "Only ads shown in this country. Use 'anywhere' for all regions. Value is an ISO 3166 two-letter code. Example: \"US\" or \"DE\".", "default": "anywhere" }, "platform": { "title": "Google platform", "enum": [ "ALL", "SEARCH", "YOUTUBE", "SHOPPING", "MAPS", "PLAY" ], "type": "string", "description": "Only ads shown on this Google surface. Example: \"YOUTUBE\" for YouTube ads only. Note that Google only reports platforms for ads shown since September 2023.", "default": "ALL" }, "format": { "title": "Ad format", "enum": [ "ALL", "TEXT", "IMAGE", "VIDEO" ], "type": "string", "description": "Only ads of this format. Example: \"VIDEO\" for video ads only.", "default": "ALL" }, "dateFrom": { "title": "Shown from (date)", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only ads that were shown on or after this date (YYYY-MM-DD). Google only supports roughly the last 12 months. Needs 'Shown until' too, or today is used. Ignored in monitor mode. Example: \"2026-06-01\"." }, "dateTo": { "title": "Shown until (date)", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only ads that were shown on or before this date (YYYY-MM-DD). Defaults to today when 'Shown from' is set. Ignored in monitor mode. Example: \"2026-09-30\"." }, "maxAdsPerQuery": { "title": "Max ads per query", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of ad records to return for each domain, advertiser or URL. Caps your cost: you pay per ad returned. In monitor mode it caps the changes returned per query (the rest are reported next run). 0 means no limit. Example: 100.", "default": 20 }, "maxAdvertisersPerName": { "title": "Advertisers per name", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many advertiser accounts to use for each advertiser name, biggest first. Large brands often run separate accounts per country. Example: 3.", "default": 1 }, "includeDetails": { "title": "Include ad details", "type": "boolean", "description": "Makes one extra request per ad to add all creative variations and per-country data: first and last shown date per country, plus impression ranges split by platform for ads shown in the EU. Charged as a separate 'ad-details' event. Example: true.", "default": false }, "monitorStoreName": { "title": "Monitor memory name", "pattern": "^[a-zA-Z0-9-]{1,63}$", "type": "string", "description": "Name of the key-value store that remembers what each query returned in previous runs. Every query (domain, advertiser plus filters) keeps its own memory inside it. Use a different name per project or client if you want separate histories. Example: \"client-acme-ads-monitor\".", "default": "google-ads-transparency-monitor" }, "includeEndedAds": { "title": "Report ended ads", "type": "boolean", "description": "In monitor mode, also return ads that stopped running since the previous run (changeType 'ended'). Charged as the cheaper 'ended-ad' event. Example: true.", "default": true }, "endedAfterDays": { "title": "Consider an ad ended after (days)", "minimum": 1, "maximum": 60, "type": "integer", "description": "An ad counts as ended once Google has not shown it for this many days. Lower values report endings faster; higher values avoid false alarms for ads that pause briefly. Example: 3.", "default": 3 }, "baselineLookbackDays": { "title": "Baseline window (days)", "minimum": 1, "maximum": 365, "type": "integer", "description": "On the first monitor run of a query, ads shown within this many days count as the current baseline. Example: 30.", "default": 30 }, "maxScanPerQuery": { "title": "Max ads scanned per query (monitor)", "minimum": 100, "maximum": 20000, "type": "integer", "description": "Monitor mode reads every ad the advertiser is currently running to find what changed, and charges one 'monitor-check' per started 1,000 ads read per query. This caps how many ads are read per query and run, and so that cost. If a query hits the cap, ended-ad detection is skipped for that run. Example: 3000.", "default": 3000 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Google rate-limits datacenter IPs heavily, so Residential proxies are the default and recommended. Proxy traffic is included in the price and never billed to you separately. Example: {\"useApifyProxy\": true, \"apifyProxyGroups\": [\"RESIDENTIAL\"]}.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } }