{ "openapi": "3.0.1", "info": { "title": "Google Ads Scraper", "description": "Every ad an advertiser runs on Google: Search, YouTube, Shopping, Maps and Play. Search by advertiser, domain or brand; filter by country, platform, format and date. Each ad: first and last shown, days shown, preview image; details add countries, EU impressions and audience targeting.", "version": "0.1", "x-build-id": "NUa9McOTcC0qgDnl0" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/autofacts~google-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-autofacts-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/autofacts~google-ads-scraper/runs": { "post": { "operationId": "runs-sync-autofacts-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/autofacts~google-ads-scraper/run-sync": { "post": { "operationId": "run-sync-autofacts-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": { "scrapeMode": { "title": "What to scrape", "enum": [ "ads", "advertiserCheck" ], "type": "string", "description": "Ads: every ad each search finds, one row per ad. Advertiser check: one row per search, saying whether it runs Google ads under your filters, about how many, when it last ran one and who pays for them, without collecting the ads themselves. Settings that belong to the other mode are ignored, and the log names anything skipped.", "default": "ads" }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "Every ad of these advertisers. The ID is the part of an advertiser's page URL after /advertiser/, such as AR01371945870127267841; the whole page URL works too.", "items": { "type": "string" } }, "domains": { "title": "Domains", "type": "array", "description": "Every ad that leads to this website, from every advertiser running one, as Google's own domain search finds them. A bare domain such as nike.com, or any URL on the site.", "items": { "type": "string" } }, "advertiserNames": { "title": "Advertiser names", "type": "array", "description": "A company or brand name, looked up the way Google's advertiser search box does it. Of the advertisers it suggests, the one whose name contains yours as whole words and has the most ads is searched (more with Maximum advertisers per name); if none does, the first it suggests. \"Nike\" finds Nike Retail BV (about 90,000 ads) rather than a one-ad advertiser called Nike. Advertisers are ranked by all their ads; with a country, platform, format or date set, the top few are ranked again by their ads under those filters, and one with none there is passed over for the next. Every ad names the advertiser it came from, so the match can be checked; to cover every advertiser of a brand, search its domain.", "items": { "type": "string" } }, "maxAdvertisersPerName": { "title": "Maximum advertisers per name", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many of the advertisers holding each name to search, most ads first. \"Nike\" is held by Nike Retail BV (about 90,000 ads), Nike, Inc. (about 10,000), nine more Nike-named companies of up to 6,000 ads, and a long tail of people and small firms with that name. Each advertiser gets its own Maximum ads per search; without one, the first can use up Maximum results and the rest are never searched. With Advertiser check, each is checked, one row each. The log lists the biggest ones left out, with their IDs.", "default": 1 }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Pages copied from adstransparency.google.com: an advertiser's page, a single ad's page, or a domain search. Filters named in a URL (region, platform, format, start-date, end-date) apply to that URL in place of the ones below; the ones below apply to the rest.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "region": { "title": "Country", "enum": [ "anywhere", "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", "KH", "CM", "CA", "CV", "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", "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", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "ES", "LK", "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. Google's figures are per country: for a country in the European Union, the ad details include impression ranges and the advertiser's audience selection.", "default": "anywhere" }, "platform": { "title": "Platform", "enum": [ "ANY", "SEARCH", "YOUTUBE", "SHOPPING", "MAPS", "PLAY" ], "type": "string", "description": "Only ads shown on this Google platform.", "default": "ANY" }, "adFormat": { "title": "Ad format", "enum": [ "ANY", "TEXT", "IMAGE", "VIDEO" ], "type": "string", "description": "Only ads of this format.", "default": "ANY" }, "dateFrom": { "title": "Shown on or after", "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$|^(\\d+)\\s*(day|week|month|year)s?$", "type": "string", "description": "Only ads shown on or after this day. A span such as \"30 days\" counts back from the day the run starts, so a scheduled run keeps looking at the latest days." }, "dateTo": { "title": "Shown on or before", "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$|^(\\d+)\\s*(day|week|month|year)s?$", "type": "string", "description": "Only ads shown on or before this day. Leave empty for today." }, "maxItems": { "title": "Maximum results", "minimum": 1, "type": "integer", "description": "Stop after storing this many rows, across all searches: ads or, with Advertiser check, searches checked. This caps what the run's rows can cost; with Only new ads on, the pages read to find new ads are charged besides, up to the maximum cost you set for the run.", "default": 100 }, "maxAdsPerSearch": { "title": "Maximum ads per search", "minimum": 1, "type": "integer", "description": "Stop each advertiser, domain or URL after this many ads (for a name, each of its advertisers), so one big advertiser cannot use up the whole run. Leave empty for no limit per search." }, "storeName": { "title": "Memory name", "pattern": "^([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)?$", "type": "string", "description": "Name a memory to keep which ads this task delivers, so that its next runs can skip them with Only new ads. Use one name per scheduled task, such as \"nike-us-daily\": lower-case letters, digits and hyphens, and a name no store in your account has yet, since the Actor creates the store and can use only the stores it created. Leave empty for a one-off run." }, "onlyNewAds": { "title": "Only new ads", "type": "boolean", "description": "Deliver only ads that no earlier run with this memory delivered. Needs a memory name. Ads skipped are not charged; each page of up to 100 ads the run reads to find the new ones is charged as a watched page. The first run delivers every ad it finds, unless Start from now is on; until a search has been read to its end once, each run reads it from the start, so let the run's maximum cost cover it.", "default": false }, "seenRetentionDays": { "title": "Remember ads for", "minimum": 14, "maximum": 3650, "type": "integer", "description": "How many days an ad stays remembered after the last run that saw it: at least 14, since each search is read in full about once a week, and at least the time between two runs; the default 30 covers any schedule with up to 30 days between runs, and 31 a monthly one. An ad forgotten while it is still listed is delivered, and charged, again; one that stops and comes back after this many days is delivered as new.", "default": 30 }, "startFromNow": { "title": "Start from now", "type": "boolean", "description": "Monitoring of each search begins the day it is first run with this on: that day reads nothing and delivers nothing, and later runs deliver only ads first shown after it — never one first shown before, even if it runs again, nor one whose first day Google does not give. Needs Only new ads. A search this memory had already read to its end keeps going as it was.", "default": false }, "includeDetails": { "title": "Include ad details", "type": "boolean", "description": "Every country the ad ran in, with the first and last day it ran there, and the topic Google labels it with. For ads shown in the European Union also the impression ranges, in total, by country and by platform, and which kinds of audience criteria the advertiser included or excluded. One extra lookup per ad, included in the price of an ad.", "default": false }, "includeAdContent": { "title": "Include ad content", "type": "boolean", "description": "What the ad says and shows, for ads Google renders live rather than as a picture: a text ad's headline and description, a Shopping ad's products (name, merchant, image), the YouTube video a video ad plays, and the landing page where the preview links to one (video ads and display product ads). One extra lookup per such ad, charged only when something is found. An ad listed as a picture is first looked up for a variation Google renders live, at no charge.", "default": false }, "onlyAdsWithText": { "title": "Only ads with text", "type": "boolean", "description": "Keep only ads whose headline or description the run reads, and leave out the rest: video and Shopping ads, ads Google keeps only as a picture, and ads whose text could not be loaded. Ads left out are not stored or charged; the run's SUMMARY record counts them, those whose text could not be loaded apart, since running again may read them. Needs 'Include ad content' on. A search reads about 20 ads for every ad it may store and then moves on, and after about 20 times Maximum results over all searches the run makes no further searches. An ad asked for by its own page URL is always kept. In testing it read about 2.6 ads a second, so with a large Maximum results and few ads with text, give the run a longer timeout.", "default": false }, "proxy": { "title": "Proxy", "type": "object", "description": "Used for every request the actor makes. Apify residential proxies by default: Google limits how many requests one address may send, and in testing on 2026-09-28 it refused between 7% and 83% of requests from shared datacenter addresses and 6 in 1,217 (0.5%) from residential ones. A refused request is sent again from another address either way.", "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 } } } } } } } } } }