{
"openapi": "3.0.1",
"info": {
"title": "Google Search Scraper",
"description": "Google results from any country domain with the real destination URL resolved, plus the people-also-ask and related-search blocks. Positions are compared between runs for the domains you track, so it doubles as a rank tracker. Example: two keywords on google.fr, scheduled weekly.",
"version": "1.0",
"x-build-id": "CxjaAd7PK8yVRFbnE"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/badr_xba~google-search-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-badr_xba-google-search-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/badr_xba~google-search-scraper/runs": {
"post": {
"operationId": "runs-sync-badr_xba-google-search-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/badr_xba~google-search-scraper/run-sync": {
"post": {
"operationId": "run-sync-badr_xba-google-search-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 queries",
"type": "array",
"description": "One search per line, exactly as you would type it in Google: best running shoes, site:example.com pricing, \"exact phrase\" review. A block of lines pasted into one item is split, extra spaces and duplicates are removed. You can also paste a full Google URL (https://www.google.fr/search?q=...) to reuse your own parameters.",
"default": [
"best running shoes"
],
"items": {
"type": "string"
}
},
"googleDomain": {
"title": "Google domain",
"enum": [
"www.google.com",
"www.google.co.uk",
"www.google.ca",
"www.google.com.au",
"www.google.de",
"www.google.fr",
"www.google.es",
"www.google.it",
"www.google.nl",
"www.google.be",
"www.google.pl",
"www.google.se",
"www.google.com.tr",
"www.google.ru",
"www.google.co.jp",
"www.google.co.kr",
"www.google.com.hk",
"www.google.co.id",
"www.google.co.in",
"www.google.com.sg",
"www.google.com.br",
"www.google.com.mx",
"www.google.com.ar",
"www.google.ae",
"www.google.com.sa",
"www.google.com.eg",
"www.google.ma",
"www.google.dz",
"www.google.tn",
"www.google.com.ng",
"www.google.co.ke",
"www.google.sn",
"www.google.co.za"
],
"type": "string",
"description": "Which national Google to query. The domain changes the results a lot: google.de does not answer like google.com. Country missing from the list? Paste a full Google URL in Search queries instead.",
"default": "www.google.com"
},
"countryCode": {
"title": "Country of results",
"type": "string",
"description": "Two-letter country code (Google's “gl” parameter): us, gb, de, fr, br, in, ma… Leave empty not to force a country.",
"default": ""
},
"languageCode": {
"title": "Language of results",
"type": "string",
"description": "Two-letter language code (Google's “hl” parameter): en, es, de, fr, pt, ar, ja… Leave empty for the domain default.",
"default": ""
},
"locationUule": {
"title": "Precise location (UULE)",
"type": "string",
"description": "Optional, for local searches: the UULE code of a city. Leave empty if you do not know what it is.",
"default": ""
},
"maxPagesPerQuery": {
"title": "Pages per query",
"minimum": 1,
"maximum": 20,
"type": "integer",
"description": "How many result pages to read for each search. Expect about ten results per page.",
"default": 1
},
"mobileResults": {
"title": "Mobile results",
"type": "boolean",
"description": "Switch on to see the ranking as it appears on a phone, which often differs from desktop.",
"default": false
},
"includePaidResults": {
"title": "Include ads",
"type": "boolean",
"description": "Adds sponsored listings to the organic results. Note that the no-JavaScript page the Actor reads does not always show ads.",
"default": true
},
"oneRowPerResult": {
"title": "One row per result",
"type": "boolean",
"description": "On: each result is a row, ready for a spreadsheet. Off: one row per result page, with the results nested inside.",
"default": true
},
"trackedDomains": {
"title": "Tracked domains",
"type": "array",
"description": "Your sites, or your competitors’. For these domains the Actor adds the previous position and the movement since the last run.",
"items": {
"type": "string"
}
},
"trackRankChanges": {
"title": "Track position changes",
"type": "boolean",
"description": "Remembers positions between runs to report gains and losses. Most useful with a daily schedule.",
"default": true
},
"maxAttemptsPerPage": {
"title": "Attempts per page",
"minimum": 1,
"maximum": 12,
"type": "integer",
"description": "How many times to retry when Google does not answer in time or returns an error (Apify's SERP proxy is sometimes slow). Failed pages are never charged.",
"default": 4
},
"maxConcurrency": {
"title": "Searches at the same time",
"minimum": 1,
"maximum": 16,
"type": "integer",
"description": "How many of your queries run in parallel. Google's SERP proxy takes several seconds per page, so running queries one after another wastes most of the run. Ten was the fastest setting measured — 100 results a minute, against 83 at sixteen and 68 at five: past ten, Google slows the proxy down and the retries eat the gain. Each query still reads its own pages in order.",
"default": 10
},
"includeHtml": {
"title": "Save the raw HTML",
"type": "boolean",
"description": "Stores Google's original page in the run's storage. For troubleshooting only: it makes runs much heavier.",
"default": false
},
"focusOnPaidAds": {
"title": "📢 Add-on: Paid results (ads) extraction ($)",
"type": "boolean",
"description": "Capture the Google Ads shown for each query. Billed per results page where at least one ad was captured.",
"default": false
},
"websiteContentScraper": {
"title": "🔍 Add-on: Full website content ($)",
"type": "object",
"description": "Set {\"enable\": true} to read the page of every organic result and attach its title, text and markdown as websiteContent. Billed per page successfully read (pages that show no text without JavaScript are not billed).",
"default": {
"enable": false
}
},
"forceExactMatch": {
"title": "Force exact match",
"type": "boolean",
"description": "Wraps each search in quotes to search the exact phrase. Fewer results.",
"default": false
},
"site": {
"title": "Site",
"type": "string",
"description": "Only results from this site (site:example.com). Takes precedence over Related to site."
},
"relatedToSite": {
"title": "Related to site",
"type": "string",
"description": "Pages related to a site (related:example.com)."
},
"wordsInTitle": {
"title": "Words in title",
"type": "array",
"description": "Each word or phrase must be in the page title (intitle:).",
"default": [],
"items": {
"type": "string"
}
},
"wordsInText": {
"title": "Words in text",
"type": "array",
"description": "Each word or phrase must be in the page text (intext:).",
"default": [],
"items": {
"type": "string"
}
},
"wordsInUrl": {
"title": "Words in URL",
"type": "array",
"description": "Each word must be in the page URL (inurl:).",
"default": [],
"items": {
"type": "string"
}
},
"quickDateRange": {
"title": "Quick date range",
"type": "string",
"description": "Results from the past h[hours], d[days], w[weeks], m[months] or y[years]: d10, w2, m6, y1. Do not combine with Before / After date."
},
"beforeDate": {
"title": "Before date",
"type": "string",
"description": "Results published before this date: 2024-12-31 or \"3 months\" (UTC)."
},
"afterDate": {
"title": "After date",
"type": "string",
"description": "Results published after this date: 2024-01-01 or \"8 days\" (UTC)."
},
"fileTypes": {
"title": "File types",
"type": "array",
"description": "Only these file types (filetype:pdf OR filetype:doc).",
"items": {
"type": "string",
"enum": [
"pdf",
"doc",
"docx",
"xls",
"xlsx",
"ppt",
"pptx",
"txt",
"rtf",
"csv",
"xml",
"kml",
"swf",
"ps"
]
},
"default": []
},
"searchLanguage": {
"title": "Search language",
"enum": [
"",
"ar",
"bg",
"ca",
"cs",
"da",
"de",
"el",
"en",
"es",
"et",
"fi",
"fr",
"hr",
"hu",
"id",
"is",
"it",
"iw",
"ja",
"ko",
"lt",
"lv",
"nl",
"no",
"pl",
"pt",
"ro",
"ru",
"sk",
"sl",
"sr",
"sv",
"th",
"tr",
"uk",
"zh-CN",
"zh-TW"
],
"type": "string",
"description": "Only pages written in this language (Google lr parameter).",
"default": ""
},
"includeUnfilteredResults": {
"title": "Unfiltered results",
"type": "boolean",
"description": "Include the lower-quality results Google normally filters out.",
"default": false
},
"saveHtml": {
"title": "Save HTML to dataset",
"type": "boolean",
"description": "Store each results page HTML in the dataset (html field). Makes the dataset large.",
"default": false
},
"saveHtmlToKeyValueStore": {
"title": "Save HTML to key-value store",
"type": "boolean",
"description": "Store each results page in the key-value store and link it in htmlSnapshotUrl, to check results in a browser.",
"default": false
},
"proxyConfiguration": {
"title": "Proxy",
"type": "object",
"description": "Google blocks datacenter servers. Keep the GOOGLE_SERP group: it is Apify's proxy built for Google Search, and it is included in your plan.",
"default": {
"useApifyProxy": true,
"apifyProxyGroups": [
"GOOGLE_SERP"
]
}
}
}
},
"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
}
}
}
}
}
}
}
}
}
}