{ "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": "u7qkI1VQq2Nbhxx7H" }, "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": { "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: \"Nike\" finds Nike, Inc., not a one-ad advertiser called Nike. 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" } }, "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 ads", "minimum": 1, "type": "integer", "description": "Stop after storing this many ads, across all searches. This is the hard cap on what the run can charge.", "default": 100 }, "maxAdsPerSearch": { "title": "Maximum ads per search", "minimum": 1, "type": "integer", "description": "Stop each advertiser, domain, name or URL after this many ads, so one big advertiser cannot use up the whole run. Leave empty for no limit per search." }, "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, charged as an extra per 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 ads 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 ads 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 } } } } } } } } } }