{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper: Ads & New-Ad Monitor", "description": "Scrape ads from the Google Ads Transparency Center by brand, domain, advertiser ID or URL. Get creatives, images, first/last shown dates, variations and regions, filter by country, platform, format and date, and monitor competitors with only-new-ads mode.", "version": "0.1", "x-build-id": "xSFdGHJ4jpHytlSpc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lasting_bonnethead~google-ads-transparency/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lasting_bonnethead-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/lasting_bonnethead~google-ads-transparency/runs": { "post": { "operationId": "runs-sync-lasting_bonnethead-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/lasting_bonnethead~google-ads-transparency/run-sync": { "post": { "operationId": "run-sync-lasting_bonnethead-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": { "queries": { "title": "Search queries (brand names or domains)", "type": "array", "description": "Brand / advertiser names (e.g. \"Nike\") or bare domains (e.g. \"nike.com\"). Names are resolved through the Transparency Center autocomplete to the best-matching verified advertisers (see \"Max advertisers per query\"); domains search every ad that points to that domain. Advertiser IDs (AR…) and Transparency Center URLs are also accepted here.", "items": { "type": "string" } }, "domains": { "title": "Domains", "type": "array", "description": "Exact advertised domains, e.g. booking.com. Protocol, www. and paths are stripped.", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Transparency Center advertiser IDs, e.g. AR16735076323512287233 (the ID in an advertiser page URL).", "items": { "type": "string" } }, "startUrls": { "title": "Transparency Center URLs", "type": "array", "description": "Paste URLs from adstransparency.google.com: advertiser pages (/advertiser/AR…), single ads (/advertiser/AR…/creative/CR…) or domain searches (/?domain=nike.com). Filters in the URL (region, platform, format, start-date, end-date, preset-date) override the filters below for that URL.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "resultType": { "title": "Result type", "enum": [ "ads", "advertisers" ], "type": "string", "description": "Ads: one row per ad creative. Advertisers: one row per advertiser with name, country and approximate ad count.", "default": "ads" }, "region": { "title": "Region", "enum": [ "ANYWHERE", "AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "CV", "KH", "CM", "CA", "IC", "BQ", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CK", "CR", "CI", "HR", "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", "HN", "HK", "HU", "IS", "IN", "ID", "IQ", "IE", "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", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "RE", "RO", "RW", "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", "SD", "SR", "SJ", "SE", "CH", "TW", "TJ", "TZ", "TH", "BS", "GM", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "VI", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VA", "VE", "VN", "WF", "EH", "YE", "ZM", "ZW" ], "type": "string", "description": "Only ads shown in this country (same as the region picker on the website). ANYWHERE = all regions.", "default": "US" }, "platforms": { "title": "Platforms", "type": "array", "description": "Only ads shown on these Google platforms. Leave empty for all. Each selected platform is searched separately (maxAdsPerSearch applies per platform); ads found on several are output once.", "items": { "type": "string", "enum": [ "SEARCH", "YOUTUBE", "SHOPPING", "MAPS", "PLAY" ], "enumTitles": [ "Google Search", "YouTube", "Google Shopping", "Google Maps", "Google Play" ] } }, "adFormat": { "title": "Ad format", "enum": [ "ALL", "TEXT", "IMAGE", "VIDEO" ], "type": "string", "description": "Only ads of this format.", "default": "ALL" }, "startDate": { "title": "Shown from", "type": "string", "description": "Only ads shown on or after this date (YYYY-MM-DD, or relative like \"30 days\"). Uses the Transparency Center's own date filter." }, "endDate": { "title": "Shown until", "type": "string", "description": "Only ads shown on or before this date (inclusive, YYYY-MM-DD)." }, "maxAdsPerSearch": { "title": "Max ads per search", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum ads scanned per input (query, domain, advertiser ID or URL). Ads come newest-activity first. Hard cap 5,000 (higher values are clamped).", "default": 100 }, "maxAdvertisersPerQuery": { "title": "Max advertisers per query", "minimum": 1, "maximum": 50, "type": "integer", "description": "For brand-name queries: how many matching advertisers to include. Exact name matches (ignoring Inc., LLC, Ltd…) come first, then by ad volume. Brands often run ads under several advertiser accounts.", "default": 5 }, "includeDetails": { "title": "Include ad details (variations + regions)", "type": "boolean", "description": "One extra request per ad to get every creative variation (all image/text versions) and the per-country breakdown (regions shown, last shown date, impression ranges per platform where published). Charged as an extra \"ad-detail\" event.", "default": false }, "detailConcurrency": { "title": "Detail concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "Parallel detail requests. Lower it if you see many 429 warnings.", "default": 6 }, "onlyNewAds": { "title": "Only new ads (monitor mode)", "type": "boolean", "description": "Return (and charge for) only ads not delivered by previous runs that used the same monitor store. The first run returns everything it finds and remembers it. Ideal for daily schedules.", "default": false }, "monitorStoreName": { "title": "Monitor store name", "type": "string", "description": "Named key-value store that remembers seen creative IDs. Use a different name per monitor (e.g. \"nike-us-monitor\") if you want them independent.", "default": "ads-transparency-monitor" }, "includeRawData": { "title": "Include raw data", "type": "boolean", "description": "Attach the raw Transparency Center payloads to each row (field \"raw\"). For debugging / power users.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy is recommended (residential by default) so Google does not rate-limit the run.", "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 } } } } } } } } } }