{ "openapi": "3.0.1", "info": { "title": "Google Ads Scraper — Live Search Sponsored Ads", "description": "Scrape LIVE Google Search sponsored ads by keyword, location, and device. One row per paid ad. Not Transparency Center.", "version": "1.0", "x-build-id": "lQPShBCslcY8whefk" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~google-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-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/khadinakbar~google-ads-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-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/khadinakbar~google-ads-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-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", "required": [ "queries" ], "properties": { "queries": { "title": "Search keywords", "type": "array", "description": "Keywords to search on Google. The scraper returns the SPONSORED (paid) ads shown for each keyword, one record per ad. Example: ['car insurance', 'crm software']. This is live SERP ad data, NOT Google Ads Transparency Center creatives — for advertiser creative history use a Transparency Center scraper instead.", "items": { "type": "string" } }, "countryCode": { "title": "Country", "enum": [ "us", "gb", "ca", "au", "de", "fr", "es", "it", "nl", "in", "br", "mx", "jp", "ae", "sg", "za" ], "type": "string", "description": "Two-letter ISO country code that geo-targets the Google search (the gl parameter), e.g. 'us', 'gb', 'de'. Ads are country-specific, so this strongly affects which advertisers appear. Defaults to 'us'. For city-level targeting also set locationName.", "default": "us" }, "languageCode": { "title": "Language", "enum": [ "en", "de", "fr", "es", "it", "nl", "pt", "ja", "ar", "hi" ], "type": "string", "description": "Two-letter ISO language code for the Google interface and results (the hl parameter), e.g. 'en', 'de', 'fr'. Defaults to 'en'. Set this to the language advertisers in your target country actually bid in, not your own.", "default": "en" }, "locationName": { "title": "City location (optional)", "type": "string", "description": "Optional canonical location for city-level ad targeting via Google's uule parameter, e.g. 'New York,New York,United States' or 'London,England,United Kingdom'. Use the exact 'City,Region,Country' form. Leave blank to target the whole country set by countryCode. NOT a latitude/longitude." }, "device": { "title": "Device", "enum": [ "desktop", "mobile" ], "type": "string", "description": "Whether to fetch the desktop or mobile Google results page. Mobile and desktop often show different ads and ad counts, so pick the surface you want to monitor. Defaults to 'desktop'.", "default": "desktop" }, "maxAdsPerQuery": { "title": "Max ads per keyword (cost cap)", "minimum": 1, "maximum": 100, "type": "integer", "description": "Hard cap on how many ads are saved and billed per keyword. This is your cost control: total max cost = number of keywords x maxAdsPerQuery x $0.008. Defaults to 20. A typical SERP shows 3-7 ads, so 20 rarely truncates. Range 1-100.", "default": 20 }, "maxPagesPerQuery": { "title": "Pages per keyword", "minimum": 1, "maximum": 5, "type": "integer", "description": "How many Google result pages to fetch per keyword. Ads concentrate on page 1, so the default 1 is best for most users; raise it only to capture bottom-of-funnel ads on deeper pages. Range 1-5.", "default": 1 }, "includeBottomAds": { "title": "Include bottom-of-page ads", "type": "boolean", "description": "Whether to also capture sponsored ads shown at the BOTTOM of the results page, not just the top block. Bottom ads are usually lower-bid competitors. Defaults to true. Set false to monitor only premium top-of-page ad slots.", "default": true }, "engine": { "title": "Scraping engine", "enum": [ "auto", "serpapi", "browser" ], "type": "string", "description": "How ads are fetched. 'auto' (recommended) uses the reliable SerpApi engine when a key is available (built in by default) and falls back to a stealth browser otherwise. 'serpapi' forces the API. 'browser' tries a stealth browser first and only falls back to SerpApi if Google blocks it. Most users should leave this on 'auto'.", "default": "auto" }, "serpApiKey": { "title": "SerpApi key (optional)", "type": "string", "description": "Optional: bring your own SerpApi key (serpapi.com) to use your own quota and rate limits. Leave blank to use the built-in managed key. Example: 'a1b2c3...'. This is a credential, not a search term — it is never stored in your output." } } }, "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 } } }, "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 } } } } } } } } } }