{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Center Scraper", "description": "Scrape ads from the Google Ads Transparency Center by brand, domain, advertiser ID or URL. Get text, image and video ads with dates, regions, ad copy, landing pages, YouTube IDs, EU impressions and advertiser profiles.", "version": "1.0", "x-build-id": "mzI6HFbIkZMR3G7fc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mattwensey~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mattwensey-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/mattwensey~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-mattwensey-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/mattwensey~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-mattwensey-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": { "searchTerms": { "title": "Brands, advertiser names or domains", "type": "array", "description": "What to look up, one per line. A domain (e.g. nike.com) returns every ad that points to that website, from all advertiser accounts. A brand or advertiser name (e.g. Nike) is matched to the advertiser account(s) with that name through the site's own search; see \"Advertisers per name\". Advertiser IDs (AR…) and Transparency Center URLs also work here.", "items": { "type": "string" } }, "startUrls": { "title": "Ads Transparency Center URLs", "type": "array", "description": "Paste links copied from adstransparency.google.com: advertiser pages (/advertiser/AR…), single ads (/advertiser/AR…/creative/CR…), domain searches (/?domain=…) or political ads pages (/political?region=…). Filters in the link (region, format, platform, dates, political topic) are used for that link and override the filters below.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Advertiser IDs start with AR followed by about 20 digits, e.g. AR16735076323512287233. You can find them in the URL of an advertiser page on the site, or in the advertiserId field of earlier results.", "items": { "type": "string" } }, "domains": { "title": "Domains", "type": "array", "description": "Exact website domains, e.g. hellofresh.com. Returns ads from every advertiser account whose ads point to the domain (brands often run several accounts, plus agencies and resellers). \"www.\" and paths are removed automatically.", "items": { "type": "string" } }, "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. \"Anywhere\" covers all regions. Google publishes impression counts and audience details only for EU countries (and for political ads).", "default": "anywhere" }, "datePreset": { "title": "Shown in", "enum": [ "ANY_TIME", "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "LAST_90_DAYS", "LAST_365_DAYS" ], "type": "string", "description": "Only ads shown during this period (ending yesterday, like on the website). Ignored when you set custom dates below.", "default": "ANY_TIME" }, "startDate": { "title": "Shown from (custom)", "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$", "type": "string", "description": "Custom range start (YYYY-MM-DD). Returns ads that were shown at least once between this date and \"Shown until\". Leave empty to use \"Shown in\"." }, "endDate": { "title": "Shown until (custom)", "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$", "type": "string", "description": "Custom range end (YYYY-MM-DD, inclusive). Defaults to today when only \"Shown from\" is set." }, "format": { "title": "Ad format", "enum": [ "ALL", "TEXT", "IMAGE", "VIDEO" ], "type": "string", "description": "Only ads of this format. Text = search ads, Image = display and Shopping ads, Video = YouTube and other video ads.", "default": "ALL" }, "platform": { "title": "Platform", "enum": [ "ALL", "SEARCH", "YOUTUBE", "SHOPPING", "MAPS", "PLAY" ], "type": "string", "description": "Only ads shown on this Google platform. Google applies this filter only to ads shown since September 2023.", "default": "ALL" }, "politicalAdsOnly": { "title": "Political ads only", "type": "boolean", "description": "Search the political ads library instead (needs one of the regions where Google publishes political ads: US, GB, BR, IN, AU, MX, AR, CL, IL, NZ, ZA or TW). Political ads include impression and spend ranges. With no other input, use a political URL such as https://adstransparency.google.com/political?region=US.", "default": false }, "politicalSort": { "title": "Political ads order", "enum": [ "MOST_RECENT", "AMOUNT_SPENT", "TIMES_SHOWN" ], "type": "string", "description": "Order of political ads (like on the website). Only used with \"Political ads only\" or political URLs.", "default": "MOST_RECENT" }, "maxAdsPerTarget": { "title": "Max ads per search", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Most recently shown ads to return for each name, domain, advertiser ID or URL. Big brands have thousands of ads. Set 0 with \"Include advertiser profiles\" on to only check advertisers (no ads).", "default": 100 }, "maxTotalAds": { "title": "Max ads in total", "minimum": 1, "type": "integer", "description": "Optional cap on ads for the whole run, across all searches. Leave empty for no cap. You can also set a maximum cost per run in the run options." }, "maxAdvertisersPerSearchTerm": { "title": "Advertisers per name", "minimum": 1, "maximum": 20, "type": "integer", "description": "When you search a brand or advertiser name, how many matching advertiser accounts to scrape, the ones with the most ads first. Brands often run one account per country, so raise this (or search the domain) to cover them all.", "default": 1 }, "includeAdDetails": { "title": "Include ad details (extra charge per ad)", "type": "boolean", "description": "Opens every ad's detail record and preview to add: ad copy (headline, description, display URL, sitelinks, call to action), landing page URL, YouTube video ID, Shopping product title, all variations, the regions where the ad ran with last-shown dates, and for EU regions impression ranges per platform, audience targeting and ad topic. Slower; charged as an extra event per ad.", "default": false }, "ocrTextAds": { "title": "Read text ads shown as images (OCR)", "type": "boolean", "description": "Google shows most search text ads only as a picture. With ad details on, this reads the picture to fill headline, description, display URL, sitelinks and other extensions (adTextSource = \"ocr\", with an ocrConfidence score; text read with low confidence is left empty). English is always used, plus the language suggested by your region filter, the ad's display URL (e.g. .de) or its wording; ads in other scripts (e.g. Japanese, Thai, Hebrew) are retried with the languages of the countries where they ran. OCR is CPU-heavy: give the run more memory (e.g. 4 GB) for large jobs, or turn this off if you only need the pictures.", "default": true }, "includeAdvertiserInfo": { "title": "Include advertiser profiles", "type": "boolean", "description": "Also saves one row per advertiser (type \"advertiser\") with legal name, country, verification status, political-ads flag and the approximate number of ads matching your filters. Charged per advertiser.", "default": false }, "onlyNewAds": { "title": "Only new ads (monitoring)", "type": "boolean", "description": "Return only ads that earlier runs with the same monitor name have not returned yet. Ideal for scheduled competitor monitoring: you only pay for new ads. The first run returns everything and remembers it.", "default": false }, "monitorStoreName": { "title": "Monitor name", "type": "string", "description": "Name of the key-value store in your account that remembers which ads were already returned. Use a different name for each set of competitors you monitor.", "default": "google-ads-transparency-monitor" }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Google limits how many requests one IP address can make. The default Apify datacenter proxy works for most runs; requests that keep getting rate-limited are retried automatically through residential proxies. Choose RESIDENTIAL here for the highest reliability on very large runs.", "default": { "useApifyProxy": true } }, "maxConcurrency": { "title": "Parallel searches", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many searches run at the same time. Higher is faster but more likely to be rate-limited by Google.", "default": 3 } } }, "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 } } } } } } } } } }