Web search (/search)

Reference for /search: web search parameters, response fields, code in 5 languages, GET and POST forms, and a sample response.

Updated View as Markdown

Organic Google results, plus the video carousel (videos) and Top stories (news) when the page has them. Results are in organic, videos, news. The product page is Google Search API.

Try in PlaygroundOpens the dashboard playground with this request filled in (sign in first).

Request

POST https://api.bestserp.com/search with a JSON body, or GET https://api.bestserp.com/search with the same parameters in the query string. The key goes in the X-API-KEY header either way (authentication).

POST
curl -X POST 'https://api.bestserp.com/search' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"q":"best running shoes"}'
GET
curl -G 'https://api.bestserp.com/search' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  --data-urlencode 'q=best running shoes'

Parameters

Unknown parameters are refused (unknown_parameter), so a typo never goes unnoticed.

ParameterTypeDefaultDescription
qrequiredstringSearch query (1–256 characters).
glstringusCountry, 2-letter code (us, gb, vn, de…). The search runs from an IP in that country when one is free, else from another one (see ipCountry).
hlstringenInterface language (en, vi, de…).
numinteger10Maximum results per page: 10, 20, 30, 40 or 50 (Google may return fewer, e.g. 8 or 9 of 10). Each 10 costs 1 credit.
pageinteger1Page to return, 1–5 (page × num/10 ≤ 5). Pages 1…page are fetched and charged.
tbsstringRecency: qdr:h (hour), qdr:d (day), qdr:w (week), qdr:m (month), qdr:y (year). Also accepted: timeRange = hour|day|week|month|year.
resolveLinksbooleantrueReplace Google redirect links with final URLs. Results come back at once with linksPending: true; poll the request for final links.
noCachebooleanfalseSkip the 1-hour result cache (5 minutes for news).
asyncbooleanfalseAnswer 202 immediately with a requestId to poll.
timeoutnumber60Seconds to wait before answering 202 (1–120).
autocorrectbooleanAccepted for compatibility; no effect.

Response fields

Empty fields are left out of each item.

organic[]

FieldMeaning
positionRank of the result in Google's order, from 1.
titleTitle of the result as Google shows it.
linkDestination URL. With resolveLinks (the default) Google redirect links are replaced by the final URL; unresolvedLinks counts any that are left.
snippetText shown under the title.
displayedLinkThe URL line as Google displays it, e.g. https://example.com › guides.
sourceSite name shown next to the result.
domainHost name of the result, without www.
faviconSite icon: a data: URI taken from the page, or a favicon service URL for the domain.

videos[]

FieldMeaning
positionRank of the video, from 1.
titleVideo title.
linkVideo page URL.
snippetDescription shown under the title, when there is one.
durationLength as displayed, e.g. 12:41.
channelChannel or uploader.
platformSite hosting the video, e.g. YouTube.
dateUpload date as displayed.
imageUrlThumbnail as an inline data: URI, only with includeThumbnails: true (about 20 KB each).

news[]

FieldMeaning
positionRank of the article, from 1.
titleHeadline.
linkArticle URL (Google redirect links are resolved as for web results).
snippetSummary shown under the headline, when there is one.
datePublish time as displayed, e.g. "2 hours ago" (ISO 8601 when the RSS fallback was used).
publishedAtPublish time in ISO 8601 UTC, when it can be determined.
sourcePublisher name.
imageUrlThumbnail as an inline data: URI, only with includeThumbnails: true (about 20 KB each).
domainHost name of the article, without www.
faviconPublisher icon.
origingoogle_search for the News tab; google_news_rss when the News tab was blocked and the Google News RSS feed was used instead (its ranking differs).

Every response

FieldMeaning
searchParametersYour request after validation, with defaults filled in (q, gl, hl, type, page or pages...).
requestIdID of this request. Poll GET /requests/{requestId} for async requests and for final links.
creditsCredits charged for this request (refunded automatically if it fails).
cachedtrue when the answer came from the recent-result cache (1 hour, 5 minutes for news).
linksPendingtrue while Google redirect links are being replaced by final URLs; poll the request to get them.
unresolvedLinksLinks that are still Google redirects: they work, but are not the final URL.
durationMsTime the search took, in milliseconds.
ipCountryCountry of the IP the search ran from (same code as gl). Another country than gl when no IP there was free: the search runs anyway instead of waiting. Missing when unknown.

Sample response

200 OK
{
  "searchParameters": {
    "q": "best running shoes",
    "gl": "us",
    "hl": "en",
    "type": "search",
    "num": 10,
    "page": 1,
    "engine": "google"
  },
  "organic": [
    {
      "position": 1,
      "title": "The 12 Best Running Shoes of 2026, Tested by Runners",
      "link": "https://www.runnersgearlab.com/best-running-shoes",
      "snippet": "We ran 1,200 miles in 60 pairs to find the best daily trainers, race shoes and trail runners for every budget.",
      "displayedLink": "https://www.runnersgearlab.com › best-running-shoes",
      "source": "Runners Gear Lab",
      "domain": "runnersgearlab.com",
      "favicon": "https://www.google.com/s2/favicons?domain=runnersgearlab.com&sz=64"
    },
    {
      "position": 2,
      "title": "Best Running Shoes for Beginners: A Buying Guide",
      "link": "https://www.stridemag.com/guides/running-shoes-beginners",
      "snippet": "Cushioning, drop, fit and price explained. Our picks for new runners, from $80 trainers to carbon racers.",
      "displayedLink": "https://www.stridemag.com › guides",
      "source": "Stride Magazine",
      "domain": "stridemag.com",
      "favicon": "https://www.google.com/s2/favicons?domain=stridemag.com&sz=64"
    },
    {
      "position": 3,
      "title": "Running shoe - Wikipedia",
      "link": "https://en.wikipedia.org/wiki/Running_shoe",
      "snippet": "Running shoes are designed for running. Modern running shoes have a cushioned midsole, a durable outsole and a breathable upper.",
      "displayedLink": "https://en.wikipedia.org › wiki › Running_shoe",
      "source": "Wikipedia",
      "domain": "en.wikipedia.org",
      "favicon": "https://www.google.com/s2/favicons?domain=en.wikipedia.org&sz=64"
    },
    {
      "position": 4,
      "title": "Men's Running Shoes | Free Shipping on Orders Over $50",
      "link": "https://www.trailandroad.com/mens/running-shoes",
      "snippet": "Shop road and trail running shoes from top brands. Free returns within 60 days.",
      "displayedLink": "https://www.trailandroad.com › mens › running-shoes",
      "source": "Trail & Road",
      "domain": "trailandroad.com",
      "favicon": "https://www.google.com/s2/favicons?domain=trailandroad.com&sz=64"
    }
  ],
  "videos": [
    {
      "position": 1,
      "title": "I Tested 10 Running Shoes for 500 Miles",
      "link": "https://www.youtube.com/watch?v=runshoe500",
      "duration": "18:42",
      "channel": "The Run Lab",
      "platform": "YouTube",
      "date": "2 weeks ago"
    }
  ],
  "requestId": "5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11",
  "credits": 1,
  "cached": false,
  "linksPending": false,
  "unresolvedLinks": 0,
  "durationMs": 1840
}

Limits

  • Organic results, the video carousel (videos) and Top stories (news) are returned. Ads, featured snippets, People Also Ask, the knowledge panel and related searches are not returned yet.
  • num is a maximum: a page holds up to 10 organic results and Google sometimes shows 8 or 9.
  • Up to 5 pages per request (page x num/10 <= 5); each page costs 1 credit.
  • Targeting is by country (gl) and interface language (hl). City-level location is not supported yet: a request with location is refused with an explicit error.
  • Results are what a desktop browser sees. There is no mobile SERP option yet.
  • 60 searches per minute per account by default; ask on Telegram for more.

Errors and their credit rules are on the errors page.