{"openapi":"3.1.0","info":{"title":"SerpsBot API","description":"\n**SerpsBot SERP API** provides fast, reliable, real-time access to Google Search Engine Results Pages (SERPs) through a scalable, production-ready HTTP API.\n\n## Features\n\n- **Real-time responses** – Direct SERP retrieval with no queuing\n- **Flexible query support** – Google search parameters, locales and verticals (web, news, images, videos)\n- **Structured output** – Normalized JSON with organic results, featured snippets, People Also Ask, videos, related searches and more\n\n## Authentication\n\nSend your API key in the `X-API-KEY` header:\n\n```\nX-API-KEY: your_api_key_here\n```\n\n## Billing\n\nEach successful (2xx) response is billed as one request, including a search with no results.\nFailed requests (4xx, 5xx) are free; a `503` carries `Retry-After` and is safe to retry.\n","version":"7.0"},"servers":[{"url":"https://api.serpsbot.com/v7","description":"Production"}],"paths":{"/google/organic-search":{"post":{"tags":["Google Search"],"summary":"Organic Search","description":"Returns Google organic search results.","operationId":"Organic_Search_google_organic_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKey":[]}]}},"/google/news-search":{"post":{"tags":["Google Search"],"summary":"Google News","description":"Returns Google News search results.","operationId":"Google_News_google_news_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsSearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKey":[]}]}},"/google/image-search":{"post":{"tags":["Google Search"],"summary":"Google Images","description":"Returns Google Images search results (tbm=isch).","operationId":"Google_Images_google_image_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageSearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKey":[]}]}},"/google/video-search":{"post":{"tags":["Google Search"],"summary":"Google Videos","description":"Returns Google Videos search results (tbm=vid).","operationId":"Google_Videos_google_video_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoSearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKey":[]}]}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ImageResult":{"properties":{"rank":{"type":"integer","title":"Rank"},"thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Thumbnail URL"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Large Image URL"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Page URL"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"}},"type":"object","required":["rank"],"title":"ImageResult"},"ImageSearchData":{"properties":{"images":{"items":{"$ref":"#/components/schemas/ImageResult"},"type":"array","title":"Images"},"suggestions":{"items":{"type":"string"},"type":"array","title":"Search Suggestions"}},"type":"object","title":"ImageSearchData"},"ImageSearchMetaData":{"properties":{"query":{"type":"string","title":"Query"},"gl":{"type":"string","title":"Gl","default":"us"},"hl":{"type":"string","title":"Hl","default":"en_US"},"page":{"type":"integer","title":"Page","default":1},"uule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uule"},"autocorrect":{"type":"string","title":"Autocorrect","default":"1"},"verbatim":{"type":"boolean","title":"Verbatim","default":false},"results":{"type":"integer","title":"Results"},"size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Size"},"min_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Min Size"},"color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Color"},"image_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Type"},"aspect_ratio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Aspect Ratio"},"usage_rights":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Usage Rights"},"time_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Time Range"},"date_min":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Min"},"date_max":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Max"},"tbs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tbs","description":"Computed `tbs` sent to Google."}},"type":"object","required":["query","results"],"title":"ImageSearchMetaData"},"ImageSearchRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Search Query"},"gl":{"anyOf":[{"type":"string","maxLength":10,"minLength":2},{"type":"null"}],"title":"Geographic Location","default":"us"},"hl":{"anyOf":[{"type":"string","maxLength":5},{"type":"null"}],"title":"Home Language","default":"en_US"},"page":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Page","default":1},"uule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"UULE String"},"autocorrect":{"anyOf":[{"type":"string","enum":["0","1"]},{"type":"null"}],"title":"Autocorrect","default":"1"},"verbatim":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Verbatim","default":false},"size":{"anyOf":[{"type":"string","enum":["large","medium","icon"]},{"type":"null"}],"title":"Image Size","description":"Image size filter. Maps to `tbs=isz:l|isz:m|isz:i`."},"min_size":{"anyOf":[{"type":"string","enum":["2mp","4mp","6mp","8mp","10mp","12mp","15mp","20mp"]},{"type":"null"}],"title":"Minimum Image Size","description":"Minimum megapixels filter. Maps to `tbs=islt:<mp>` (e.g. `islt:4mp`)."},"color":{"anyOf":[{"type":"string","enum":["color","gray","transparent","red","orange","yellow","green","teal","blue","purple","pink","brown","black","white"]},{"type":"null"}],"title":"Color","description":"Color filter. Maps to `ic:color|ic:gray|ic:trans` or `ic:specific,isc:<color>`."},"image_type":{"anyOf":[{"type":"string","enum":["photo","clipart","lineart","animated"]},{"type":"null"}],"title":"Image Type","description":"Type/style filter. Maps to `tbs=itp:photo|clipart|lineart|animated`."},"aspect_ratio":{"anyOf":[{"type":"string","enum":["square","wide","tall","ultrawide"]},{"type":"null"}],"title":"Aspect Ratio","description":"Aspect ratio filter. Maps to `tbs=iar:s|iar:w|iar:t|iar:xw`."},"usage_rights":{"anyOf":[{"type":"string","enum":["f","fc","fm","fmc"]},{"type":"null"}],"title":"Usage Rights","description":"Usage rights filter. Maps to `tbs=sur:<code>` (e.g. `sur:f`, `sur:fc`, `sur:fm`, `sur:fmc`)."},"time_range":{"anyOf":[{"type":"string","enum":["h","d","w","m","y"]},{"type":"null"}],"title":"Time Range","description":"Recency filter (past hour/day/week/month/year). Maps to `tbs=qdr:<unit>`."},"date_min":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Min","description":"Custom date range start (YYYY-MM-DD or MM/DD/YYYY). Uses `tbs=cdr:1,cd_min:...,cd_max:...`."},"date_max":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Max","description":"Custom date range end (YYYY-MM-DD or MM/DD/YYYY). Uses `tbs=cdr:1,cd_min:...,cd_max:...`."}},"type":"object","required":["query"],"title":"ImageSearchRequest","description":"Request model for Google Image search (tbm=isch).\n\nSame as `SearchRequest` but excludes `parse_answers` (not used for images)."},"ImageSearchResponse":{"properties":{"meta":{"$ref":"#/components/schemas/ImageSearchMetaData","title":"Request Meta Data"},"data":{"$ref":"#/components/schemas/ImageSearchData","title":"Image Search Data"}},"type":"object","required":["meta","data"],"title":"ImageSearchResponse"},"NewsResult":{"properties":{"rank":{"type":"integer","title":"Rank"},"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"URL"},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snippet"},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date"},"publisher":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher"},"publisher_image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publisher Image URL"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"News Image URL"}},"type":"object","required":["rank","title","url"],"title":"NewsResult"},"NewsSearchMetaData":{"properties":{"query":{"type":"string","title":"Query"},"gl":{"type":"string","title":"Gl","default":"us"},"hl":{"type":"string","title":"Hl","default":"en_US"},"page":{"type":"integer","title":"Page","default":1},"uule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uule"},"autocorrect":{"type":"string","title":"Autocorrect","default":"1"},"verbatim":{"type":"boolean","title":"Verbatim","default":false},"filter":{"type":"integer","title":"Filter","description":"Duplicate filtering. 0 = show similar results, 1 = filter similar results.","default":0},"duration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duration","description":"Recency filter (past day/week/month/year).","default":"y"},"results":{"type":"integer","title":"Results"},"tbs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tbs","description":"Computed `tbs` sent to Google."}},"type":"object","required":["query","results"],"title":"NewsSearchMetaData"},"NewsSearchRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Search Query"},"gl":{"anyOf":[{"type":"string","maxLength":10,"minLength":2},{"type":"null"}],"title":"Geographic Location","default":"us"},"hl":{"anyOf":[{"type":"string","maxLength":5},{"type":"null"}],"title":"Home Language","default":"en_US"},"page":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Page","default":1},"uule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"UULE String"},"autocorrect":{"anyOf":[{"type":"string","enum":["0","1"]},{"type":"null"}],"title":"Autocorrect","default":"1"},"verbatim":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Verbatim","default":false},"filter":{"anyOf":[{"type":"integer","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Filter","description":"Duplicate filtering. 0 = show similar results, 1 = filter similar results.","default":0},"duration":{"anyOf":[{"type":"string","enum":["d","w","m","y"]},{"type":"null"}],"title":"Duration","default":"y"}},"type":"object","required":["query"],"title":"NewsSearchRequest","description":"Request model for Google News search.\n\nSame as `SearchRequest` but intentionally excludes `parse_answers`\n(News endpoint doesn't support/need it)."},"NewsSearchResponse":{"properties":{"meta":{"$ref":"#/components/schemas/NewsSearchMetaData","title":"Request Meta Data"},"data":{"items":{"$ref":"#/components/schemas/NewsResult"},"type":"array","title":"News Results"}},"type":"object","required":["meta","data"],"title":"NewsSearchResponse"},"OrganicResult":{"properties":{"rank":{"type":"integer","title":"Rank"},"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"URL"},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snippet"},"rich_snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rich Snippet"},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date"},"sitelinks":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Sitelinks"},"snippet_html":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snippet HTML","description":"Deprecated. Please use snippet.","deprecated":true,"readOnly":true}},"type":"object","required":["rank","title","url","date","sitelinks","snippet_html"],"title":"OrganicResult"},"PeopleAlsoAsk":{"properties":{"question":{"type":"string","title":"Question","description":"The question text."},"answer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answer","description":"The answer text."},"answer_type":{"type":"string","enum":["MISSING","AI","STANDARD"],"title":"Answer Type","description":"The answer type. Was it generated by AI or was extracted from a standard web source.","default":"STANDARD"},"sources":{"items":{"$ref":"#/components/schemas/WebSource"},"type":"array","title":"Web Sources","description":"The list of web sources of the answer."}},"type":"object","required":["question","sources"],"title":"PeopleAlsoAsk"},"SearchMetaData":{"properties":{"query":{"type":"string","title":"Query"},"gl":{"type":"string","title":"Gl","default":"us"},"hl":{"type":"string","title":"Hl","default":"en_US"},"safe":{"type":"boolean","title":"Safe","default":false},"filter":{"type":"integer","title":"Filter","description":"Duplicate filtering. 0 = show similar results, 1 = filter similar results.","default":0},"device":{"type":"string","title":"Device","default":"desktop"},"duration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Duration","default":"y"},"autocorrect":{"type":"string","title":"Autocorrect","default":"1"},"page":{"type":"integer","title":"Page","default":1},"uule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uule"},"verbatim":{"type":"boolean","title":"Verbatim","default":false},"results":{"type":"integer","title":"Results"}},"type":"object","required":["query","results"],"title":"SearchMetaData"},"SearchRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Search Query"},"gl":{"anyOf":[{"type":"string","maxLength":10,"minLength":2},{"type":"null"}],"title":"Geographic Location","default":"us"},"hl":{"anyOf":[{"type":"string","maxLength":5},{"type":"null"}],"title":"Home Language","default":"en_US"},"page":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Page","default":1},"uule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"UULE String"},"autocorrect":{"anyOf":[{"type":"string","enum":["0","1"]},{"type":"null"}],"title":"Autocorrect","default":"1"},"verbatim":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Verbatim","default":false},"filter":{"anyOf":[{"type":"integer","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Filter","description":"Duplicate filtering. 0 = show similar results, 1 = filter similar results.","default":0},"duration":{"anyOf":[{"type":"string","enum":["d","w","m","y"]},{"type":"null"}],"title":"Duration","default":"y"},"parse_answers":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Parse Answers","description":"By default, only questions are parsed. Parsing the answers is an expensive task. So if you don't need the answers, please leave this field as false to avoid performance issues.","default":false},"device":{"anyOf":[{"type":"string","enum":["desktop","mobile"]},{"type":"null"}],"title":"Device","default":"desktop"}},"type":"object","required":["query"],"title":"SearchRequest"},"SearchResponse":{"properties":{"meta":{"$ref":"#/components/schemas/SearchMetaData","title":"Request Meta Data"},"data":{"$ref":"#/components/schemas/SearchResults","title":"Search Results Data"}},"type":"object","required":["meta","data"],"title":"SearchResponse"},"SearchResults":{"properties":{"featured_snippet":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Featured Snippet"},"organic":{"items":{"$ref":"#/components/schemas/OrganicResult"},"type":"array","title":"Organic Results"},"videos":{"items":{"$ref":"#/components/schemas/VideoResult"},"type":"array","title":"Video Results"},"people_also_ask":{"anyOf":[{"items":{"$ref":"#/components/schemas/PeopleAlsoAsk"},"type":"array"},{"type":"null"}],"title":"People Also Ask"},"people_also_search_for":{"items":{"type":"string"},"type":"array","title":"People Also Search For"}},"type":"object","required":["organic","videos"],"title":"SearchResults"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VideoResult":{"properties":{"url":{"type":"string","title":"Video URL","description":"URL of the video."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Video Title","description":"Title of the video."},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Video Source","description":"Source of the video.","examples":["YouTube"]},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Video Author","description":"Author name of the video.","examples":["CNN"]},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Video Date","description":"The date or relative time when the video was published.","examples":["2 weeks ago"]}},"type":"object","required":["url"],"title":"VideoResult"},"VideoSearchData":{"properties":{"videos":{"items":{"$ref":"#/components/schemas/VideoResult"},"type":"array","title":"Videos"},"suggestions":{"items":{"type":"string"},"type":"array","title":"Search Suggestions"}},"type":"object","title":"VideoSearchData"},"VideoSearchMetaData":{"properties":{"query":{"type":"string","title":"Query"},"gl":{"type":"string","title":"Gl","default":"us"},"hl":{"type":"string","title":"Hl","default":"en_US"},"page":{"type":"integer","title":"Page","default":1},"uule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uule"},"autocorrect":{"type":"string","title":"Autocorrect","default":"1"},"verbatim":{"type":"boolean","title":"Verbatim","default":false},"results":{"type":"integer","title":"Results"},"uploaded_within":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uploaded Within"},"video_duration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Video Duration"},"high_quality":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"High Quality"},"closed_captions":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Closed Captions"},"sort_by_date":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Sort By Date"},"date_min":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Min"},"date_max":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Max"},"tbs":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tbs","description":"Computed `tbs` sent to Google."}},"type":"object","required":["query","results"],"title":"VideoSearchMetaData"},"VideoSearchRequest":{"properties":{"query":{"type":"string","maxLength":2000,"minLength":1,"title":"Search Query"},"gl":{"anyOf":[{"type":"string","maxLength":10,"minLength":2},{"type":"null"}],"title":"Geographic Location","default":"us"},"hl":{"anyOf":[{"type":"string","maxLength":5},{"type":"null"}],"title":"Home Language","default":"en_US"},"page":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":1.0},{"type":"null"}],"title":"Page","default":1},"uule":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"UULE String"},"autocorrect":{"anyOf":[{"type":"string","enum":["0","1"]},{"type":"null"}],"title":"Autocorrect","default":"1"},"verbatim":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Verbatim","default":false},"uploaded_within":{"anyOf":[{"type":"string","enum":["h","d","w","m","y"]},{"type":"null"}],"title":"Uploaded Within","description":"Recency filter (past hour/day/week/month/year). Maps to `tbs=qdr:<unit>`."},"video_duration":{"anyOf":[{"type":"string","enum":["short","medium","long"]},{"type":"null"}],"title":"Video Duration","description":"Filter by video length: short (<4 min), medium (4–20 min), long (>20 min)."},"high_quality":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"High Quality","description":"If true, prefer high-quality/HD videos when supported."},"closed_captions":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Closed Captions","description":"If true, only return videos with captions/subtitles when supported."},"sort_by_date":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Sort By Date","description":"If true, sort by upload date (newest first) when supported."},"date_min":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Min","description":"Custom date range start (YYYY-MM-DD or MM/DD/YYYY). Uses `tbs=cdr:1,cd_min:...,cd_max:...`."},"date_max":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date Max","description":"Custom date range end (YYYY-MM-DD or MM/DD/YYYY). Uses `tbs=cdr:1,cd_min:...,cd_max:...`."}},"type":"object","required":["query"],"title":"VideoSearchRequest","description":"Request model for Google Video search (tbm=vid).\n\nSame as `SearchRequest` but excludes `parse_answers` (not used for videos)."},"VideoSearchResponse":{"properties":{"meta":{"$ref":"#/components/schemas/VideoSearchMetaData","title":"Request Meta Data"},"data":{"$ref":"#/components/schemas/VideoSearchData","title":"Video Search Data"}},"type":"object","required":["meta","data"],"title":"VideoSearchResponse"},"WebSource":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Title"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source URL"}},"type":"object","required":["title","url"],"title":"WebSource"}},"securitySchemes":{"APIKey":{"type":"apiKey","description":"Your API key, issued from the developer portal.","in":"header","name":"X-API-KEY"}}}}