{ "openapi": "3.1.0", "info": { "title": "Google Search API", "version": "1.0.0", "description": "Google web results with People also ask, related searches, top stories, local results and the knowledge panel, rank checks and search suggestions, exposed through FetchLayer as structured JSON." }, "servers": [ { "url": "https://api.fetchlayer.dev/google-search" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/search": { "post": { "operationId": "search", "tags": [ "Web search" ], "summary": "Search Google web results", "description": "Google web search results for a query, as a searcher in a given country, language, city and on desktop or mobile, with everything Google shows around them. organicResults holds the organic results in rank order: position (1-based across the pages read, and across a cursor continuation), the page and its place on that page, title, destination URL and domain, the address line Google prints, the site name, snippet, the date as displayed, extensions such as \"30+ comments · 1 year ago\", and sitelinks. Around them, when Google shows them: the answer box (weather, unit conversions, featured snippets), the People also ask questions, related searches, top stories, videos and short videos, discussions, local business results with rating, review count and price level, the knowledge panel, and ads — which come back in ads and never take an organic position. A query Google finds nothing for is a 200 with noResults: true, not an error. Filter by time range and safe search. One result page is read by default; pages reads up to 10 in one request, page starts later (1–15), and nextCursor continues, sent with the same query and options. Google shows between 6 and 10 organic results a page and ignores a requested count, so limit only trims what the pages held. Results reflect a US, English, desktop searcher unless you set otherwise, and positions move with time, country and location. There is no total-result count and no AI Overview; People also ask gives the questions, not their answers; videos, shorts and discussions are detected on English-language pages only. Billing: each result page read counts as one request (pagesScraped). To find where one site ranks, use rank-check instead: it costs one request at any depth.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query, exactly as typed into Google (1–2048 characters)." }, "country": { "type": "string", "description": "Two-letter country the results are for: US, GB, DE, FR, IN, BR and so on. Case-insensitive. Rankings differ by country.", "example": "US" }, "language": { "type": "string", "description": "Interface and snippet language: en, de, fr, pt-BR and so on.", "example": "en" }, "location": { "type": "string", "description": "A city to localize results to, as a canonical location name \"City,Region,Country\", e.g. \"Austin,Texas,United States\". Local results and rankings follow it." }, "device": { "type": "string", "description": "desktop or mobile results. A mobile search takes about 15 seconds.", "example": "desktop" }, "safeSearch": { "type": "string", "description": "off, or on to filter explicit results.", "example": "off" }, "timeRange": { "type": "string", "description": "any, hour, day, week, month or year: only results from that period.", "example": "any" }, "page": { "type": "number", "description": "Result page to start from (1–15). Do not combine with cursor.", "example": "1" }, "pages": { "type": "number", "description": "Result pages to read in this request (1–10), or -1 for 10. Each page read counts as one request.", "example": "1" }, "limit": { "type": "number", "description": "Most organic results to return (1–100), or -1 for 100. Defaults to everything on the pages read." }, "cursor": { "type": "string", "description": "A previous response’s nextCursor. Send it with the same query and options." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Time limit for each result page read, in milliseconds (1000–60000)." } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "open source crm", "limit": 10 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resultType": { "type": "string", "description": "search, rank-check or autocomplete." }, "requestedUrl": { "type": "string", "description": "The Google page this result corresponds to." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a result whose link could not be followed, a page that could not be read. Empty when there are none. Read it on every call." }, "transport": { "type": "string", "description": "The source this data came from. Always \"google\"." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "parameters": { "type": "object", "additionalProperties": true, "description": "The searcher the results are for, after defaults: query, country (lower case), language, location, device, safeSearch and timeRange." }, "organicResults": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "position": { "type": "number", "description": "1-based rank among organic results across the pages in this response. Ads never take a position." }, "page": { "type": "number", "description": "The result page it appeared on." }, "pagePosition": { "type": "number", "description": "Its rank on that page." }, "title": { "type": "string", "description": "The result title." }, "url": { "type": "string", "description": "Where the result leads, or null in the rare case the destination could not be determined (a note says so)." }, "domain": { "type": "string", "description": "Hostname of url, or null." }, "displayedUrl": { "type": "string", "description": "The address line Google prints, e.g. \"https://github.com › SuiteCRM › SuiteCRM\". null on forum and social results, which print activity instead." }, "source": { "type": "string", "description": "The site name Google prints beside the result, e.g. \"Reddit · r/CRM\"." }, "snippet": { "type": "string", "description": "The description text, or null." }, "date": { "type": "string", "description": "The date printed before the snippet, as displayed (e.g. \"Jan 19, 2026\"), or null." }, "extensions": { "type": "array", "items": { "type": "string" }, "description": "Extra detail such as \"30+ comments · 1 year ago\" or \"2.7M+ followers\"." }, "sitelinks": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Sub-links shown under the result, each { title, url }." } } }, "description": "Organic results, in rank order." }, "organicCount": { "type": "number", "description": "Organic results in this response. Google publishes no total-result count." }, "ads": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Text ads, never ranked: position within their block, block (top or bottom), title, url, domain, displayedUrl, description. Google places ads by the searcher’s real location rather than by country, so when no matching vantage point is available the field is left out entirely and a note says why; organic results are unaffected. Treat ads as optional." }, "answerBox": { "type": "object", "additionalProperties": true, "description": "A direct answer — type (weather, unit_converter or featured_snippet), title, text, details ({ label, value } rows), url — or null." }, "peopleAlsoAsk": { "type": "array", "items": { "type": "string" }, "description": "The questions in the People also ask box. The answers are not returned." }, "relatedSearches": { "type": "array", "items": { "type": "string" }, "description": "The related searches Google suggests." }, "topStories": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "News stories: title, url, source, date as displayed (e.g. \"19 hours ago\") and publishedAt (ISO 8601)." }, "videos": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Videos and short videos: title, url, platform, channel, date, duration and kind (video or short). English-language pages only." }, "discussions": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Forum and social posts Google groups as discussions: title, url, source, date. English-language pages only." }, "localResults": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Businesses: position, name, rating (out of 5), reviewCount, priceLevel (e.g. \"$10–20\"), category, address, phone, hours and highlight (a review excerpt)." }, "knowledgePanel": { "type": "object", "additionalProperties": true, "description": "title, subtitle, description, descriptionSource ({ title, url }), facts ({ label, value } rows) and profiles ({ title, url }), or null." }, "noResults": { "type": "boolean", "description": "True when Google found nothing for the query." }, "page": { "type": "number", "description": "The first result page in this response." }, "pagesScraped": { "type": "number", "description": "Result pages read. Each counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "The pages this request asked for. Compare with pagesScraped." }, "hasNextPage": { "type": "boolean", "description": "Whether there are more results." }, "nextCursor": { "type": "string", "description": "Pass back as cursor, with the same query and options, to continue. null at the end." } }, "additionalProperties": false }, "examples": { "default": { "value": { "requestedUrl": "https://www.google.com/search?q=open+source+crm&hl=en&gl=us&pws=0&safe=off", "scrapedAt": "2026-09-15T20:59:33.616Z", "transport": "google", "notes": [], "resultType": "search", "parameters": { "query": "open source crm", "country": "us", "language": "en", "location": null, "device": "desktop", "safeSearch": "off", "timeRange": "any" }, "page": 1, "pagesScraped": 1, "pagesRequested": 1, "organicResults": [ { "position": 1, "page": 1, "pagePosition": 1, "title": "Twenty | #1 Open Source CRM", "url": "https://twenty.com/", "domain": "twenty.com", "displayedUrl": "https://twenty.com", "source": "Twenty", "snippet": "Twenty gives technical teams the building blocks for a custom CRM that meets complex business needs and quickly adapts as the business evolves.", "date": null, "extensions": [], "sitelinks": [] }, { "position": 2, "page": 1, "pagePosition": 2, "title": "Free Open Source CRM Software | Download EspoCRM", "url": "https://www.espocrm.com/download/", "domain": "www.espocrm.com", "displayedUrl": "https://www.espocrm.com › download", "source": "EspoCRM", "snippet": "EspoCRM is a free, open-source CRM you host on your own server. Track contacts, manage deals, handle support cases with a built-in customer portal, and run ...", "date": null, "extensions": [], "sitelinks": [] }, { "position": 3, "page": 1, "pagePosition": 3, "title": "SuiteCRM - Open source CRM for the world", "url": "https://github.com/SuiteCRM/SuiteCRM", "domain": "github.com", "displayedUrl": "https://github.com › SuiteCRM › SuiteCRM", "source": "GitHub", "snippet": "SuiteCRM is the award-winning open-source, enterprise-ready Customer Relationship Management (CRM) software application. Our vision is to be the most adopted ...", "date": null, "extensions": [], "sitelinks": [] }, { "position": 4, "page": 1, "pagePosition": 4, "title": "What’s the Best Open-Source CRM for Small and Medium ...", "url": "https://www.reddit.com/r/CRM/comments/1ij3e8h/whats_the_best_opensource_crm_for_small_and/", "domain": "www.reddit.com", "displayedUrl": null, "source": "Reddit · r/CRM", "snippet": "I work for a small company (20 people), and we’ve been looking for a CRM that is both customizable and developer-friendly. After spending a lot ...", "date": null, "extensions": [ "30+ comments · 1 year ago" ], "sitelinks": [ { "title": "Self hosted open source CRM for business purposes ...", "url": "https://www.reddit.com/r/selfhosted/comments/14xzd2v/self_hosted_open_source_crm_for_business_purposes/" } ] } ], "organicCount": 9, "ads": [], "answerBox": null, "peopleAlsoAsk": [ "What is the best open source CRM?", "Will CRM be replaced by AI?", "Is there a free CRM I can use?", "Is there a 100% free CRM?" ], "relatedSearches": [ "Open source crm github", "Open source crm free", "Best open source CRM", "Open source crm reddit", "Open source CRM self-hosted", "Open source crm docker", "Open source crm list", "Open source crm free download" ], "topStories": [], "videos": [], "discussions": [], "localResults": [], "knowledgePanel": null, "noResults": false, "hasNextPage": true, "nextCursor": "eyJ2IjoxLCJxIjoib3BlbiBzb3VyY2UgY3JtIiwiZ2wiOiJ1cyIs…" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/rank-check": { "post": { "operationId": "rank-check", "tags": [ "Web search" ], "summary": "Check where a site ranks on Google", "description": "Find where a domain or URL ranks in Google’s organic results for a query — built for SEO rank tracking. Send a query and a target and get back whether it was found, its best position, the page that position is on, the best-ranked matching URL, and every match with its position, page, place on the page, URL and title, examining up to depth organic results (1–100, default 50). match decides what counts: domain (any page of the site), exact_url (that URL only) or url_prefix (the URL and everything under it, at a path boundary, so /blog matches /blog/post but not /blogging); it defaults to domain for a bare domain and url_prefix for a URL with a path. Matching is on whole hostnames, so notexample.com and example.com.other.net never count; www. and m. always count, and other subdomains count unless includeSubdomains is false. Positions are counted exactly as search counts them — organic results only, ads never take a position. The check stops at the page where the target is first found (stoppedAtFirstMatch) unless allMatches is set. It also reports otherAppearances: where the target shows up outside the organic ranking on the pages it read — as a sitelink, an ad, in top stories, videos or discussions, in the knowledge panel or the answer box — each with its feature, page, URL and title. found: false means depthScanned results were examined, or every result Google had when there were fewer (endOfResults). Rankings differ by country, language, location and device and move over time; results reflect a US, English, desktop searcher unless you set otherwise. A deep check can take 15 seconds or more, and up to about 150 seconds when Google turns requests away. Billing: A rank check costs 1 credit regardless of depth: scanning 100 positions across 10 or more result pages is billed as one request. serpPagesFetched reports how many result pages were read and is never billed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query, exactly as typed into Google (1–2048 characters)." }, "target": { "type": "string", "description": "The site or page to find: a domain such as example.com, or a URL such as https://example.com/pricing. A leading www. and the scheme are ignored." }, "match": { "type": "string", "description": "domain, exact_url or url_prefix. Defaults to domain for a bare domain and url_prefix for a URL with a path." }, "includeSubdomains": { "type": "boolean", "description": "For a domain target, whether subdomains such as blog.example.com count.", "example": "true" }, "depth": { "type": "number", "description": "Organic results to examine at most, e.g. 10, 30, 50 or 100 (1–100). One request at any depth.", "example": "50" }, "allMatches": { "type": "boolean", "description": "Keep looking after the first match and report every matching result within the depth.", "example": "false" }, "country": { "type": "string", "description": "Two-letter country the results are for: US, GB, DE, FR, IN, BR and so on. Case-insensitive. Rankings differ by country.", "example": "US" }, "language": { "type": "string", "description": "Interface and snippet language: en, de, fr, pt-BR and so on.", "example": "en" }, "location": { "type": "string", "description": "A city to localize results to, as a canonical location name \"City,Region,Country\", e.g. \"Austin,Texas,United States\". Local results and rankings follow it." }, "device": { "type": "string", "description": "desktop or mobile results. A mobile search takes about 15 seconds.", "example": "desktop" }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Time limit for each result page read, in milliseconds (1000–60000)." } }, "additionalProperties": false, "required": [ "query", "target" ] }, "examples": { "default": { "value": { "query": "open source crm", "target": "github.com", "depth": 30 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resultType": { "type": "string", "description": "search, rank-check or autocomplete." }, "requestedUrl": { "type": "string", "description": "The Google page this result corresponds to." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a result whose link could not be followed, a page that could not be read. Empty when there are none. Read it on every call." }, "transport": { "type": "string", "description": "The source this data came from. Always \"google\"." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "parameters": { "type": "object", "additionalProperties": true, "description": "The searcher the results are for, after defaults: query, country (lower case), language, location, device, safeSearch and timeRange." }, "target": { "type": "object", "additionalProperties": true, "description": "The target as understood: input, match (domain, exact_url or url_prefix), host (without www.), path (for URL targets, else null) and includeSubdomains." }, "found": { "type": "boolean", "description": "Whether the target appears in the organic results examined." }, "position": { "type": "number", "description": "Its best organic position across pages, or null." }, "foundOnPage": { "type": "number", "description": "The result page that position is on, or null." }, "url": { "type": "string", "description": "The best-ranked matching URL, or null." }, "matches": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Every matching organic result found: position, page, pagePosition, url and title. Without allMatches, the matches on the page where the target was first found." }, "otherAppearances": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Where the target also appears on the pages examined: feature (sitelink, ad, top_stories, video, discussion, knowledge_panel or answer_box), page, url and title." }, "depthScanned": { "type": "number", "description": "Organic results examined." }, "depthRequested": { "type": "number", "description": "The depth you asked for." }, "stoppedAtFirstMatch": { "type": "boolean", "description": "True when the check stopped at the first match rather than examining the full depth." }, "endOfResults": { "type": "boolean", "description": "True when Google had fewer results than the depth." }, "serpPagesFetched": { "type": "number", "description": "Result pages read. Informational only — never billed." }, "pagesScraped": { "type": "number", "description": "Always 1: a rank check counts as one request against your plan, however many pages it reads." } }, "additionalProperties": false }, "examples": { "default": { "value": { "requestedUrl": "https://www.google.com/search?q=open+source+crm&hl=en&gl=us&pws=0&safe=off", "scrapedAt": "2026-09-15T20:59:30.000Z", "transport": "google", "notes": [], "resultType": "rank-check", "parameters": { "query": "open source crm", "country": "us", "language": "en", "location": null, "device": "desktop", "safeSearch": "off", "timeRange": "any" }, "target": { "input": "github.com", "match": "domain", "host": "github.com", "path": null, "includeSubdomains": true }, "found": true, "position": 3, "foundOnPage": 1, "url": "https://github.com/SuiteCRM/SuiteCRM", "matches": [ { "position": 3, "page": 1, "pagePosition": 3, "url": "https://github.com/SuiteCRM/SuiteCRM", "title": "SuiteCRM - Open source CRM for the world" } ], "otherAppearances": [], "depthScanned": 9, "depthRequested": 30, "stoppedAtFirstMatch": true, "endOfResults": false, "serpPagesFetched": 1, "pagesScraped": 1 } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/autocomplete": { "post": { "operationId": "autocomplete", "tags": [ "Keyword research" ], "summary": "Get Google search suggestions", "description": "The suggestions Google’s search box offers for a partial query, in Google’s order, for a country and language — useful for keyword research and for finding how people phrase a search. Takes country and language only; location, device, safe search or time range is a 400. Billing: one request.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "The partial query to complete (1–300 characters)." }, "country": { "type": "string", "description": "Two-letter country the results are for: US, GB, DE, FR, IN, BR and so on. Case-insensitive. Rankings differ by country.", "example": "US" }, "language": { "type": "string", "description": "Interface and snippet language: en, de, fr, pt-BR and so on.", "example": "en" }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Time limit for each result page read, in milliseconds (1000–60000)." } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "fetchla" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "resultType": { "type": "string", "description": "search, rank-check or autocomplete." }, "requestedUrl": { "type": "string", "description": "The Google page this result corresponds to." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a result whose link could not be followed, a page that could not be read. Empty when there are none. Read it on every call." }, "transport": { "type": "string", "description": "The source this data came from. Always \"google\"." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "query": { "type": "string", "description": "The partial query." }, "country": { "type": "string", "description": "The country the suggestions are for, in lower case." }, "language": { "type": "string", "description": "The language the suggestions are for." }, "suggestions": { "type": "array", "items": { "type": "string" }, "description": "The suggestions, in Google’s order." } }, "additionalProperties": false }, "examples": { "default": { "value": { "requestedUrl": "https://www.google.com/complete/search?q=fetchla&client=chrome&hl=en&gl=us", "scrapedAt": "2026-09-15T20:59:28.301Z", "transport": "google", "notes": [], "resultType": "autocomplete", "query": "fetchla", "country": "us", "language": "en", "suggestions": [ "fetchlands", "fetchlands mtg", "fetchlands scryfall", "fetchland prices", "fetchlands list", "fetchlab", "fetchlayer", "fetchlands moxfield" ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse a Google search URL", "description": "Turn a Google URL into the request fields it encodes, without contacting Google. A search results URL, on any Google domain (google.de/search?q=wetter+berlin&hl=de&start=10&tbs=qdr:w), comes back as kind: \"search\" with its query, country, language, location, page, safe search, time range, the results tab when it is not web results (vertical, e.g. news or images) and the Google domain — ready to send to search. A Google redirect link that names its destination comes back as kind: \"redirect\" with where it leads in target. Fields the URL does not carry are null. Any other URL is a 400 saying why. Parsing a URL does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "A Google search results URL, or a Google redirect link." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Time limit for each result page read, in milliseconds (1000–60000)." } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://www.google.de/search?q=wetter+berlin&hl=de&start=10&tbs=qdr:w" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "search or redirect." }, "url": { "type": "string", "description": "The URL you sent." }, "query": { "type": "string", "description": "The query the URL carries, or null. Pass it to search." }, "country": { "type": "string", "description": "The country (gl) the URL carries, or null." }, "language": { "type": "string", "description": "The language (hl) the URL carries, or null." }, "location": { "type": "string", "description": "The location the URL carries, or null." }, "page": { "type": "number", "description": "The result page the URL points at, or null." }, "safeSearch": { "type": "string", "description": "on or off when the URL sets it, or null." }, "timeRange": { "type": "string", "description": "hour, day, week, month, year or any when the URL sets it, or null." }, "vertical": { "type": "string", "description": "A results tab other than web results, e.g. news or images, or null." }, "googleDomain": { "type": "string", "description": "The Google domain the URL is on, e.g. google.de." }, "target": { "type": "string", "description": "For a redirect link, where it leads; otherwise null." } }, "additionalProperties": false }, "examples": { "default": { "value": { "url": "https://www.google.de/search?q=wetter+berlin&hl=de&start=10&tbs=qdr:w", "googleDomain": "google.de", "query": "wetter berlin", "country": "de", "language": "de", "location": null, "page": 2, "safeSearch": null, "timeRange": "week", "vertical": null, "target": null, "kind": "search" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }