# Web search (/search)

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

Source: https://bestserp.com/docs/api/search (updated 2026-11-14)

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](https://bestserp.com/google-search-api).

[Try this request in the Playground](https://bestserp.com/dashboard/playground?type=search&q=best+running+shoes)

## 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](https://bestserp.com/docs/authentication)).

**POST, cURL**

```bash
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"}'
```

**POST, Python**

```python
import requests

resp = requests.post(
    "https://api.bestserp.com/search",
    headers={"X-API-KEY": "YOUR_API_KEY"},
    json={
      "q": "best running shoes"
    },
    timeout=130,
)
resp.raise_for_status()
print(resp.json())
```

**POST, Node.js**

```javascript
const res = await fetch("https://api.bestserp.com/search", {
  method: "POST",
  headers: { "X-API-KEY": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    "q": "best running shoes"
  }),
});
console.log(await res.json());
```

**POST, PHP**

```php
<?php
$ch = curl_init('https://api.bestserp.com/search');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 130,
    CURLOPT_HTTPHEADER => ['X-API-KEY: YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'q' => 'best running shoes',
    ]),
]);
echo curl_exec($ch);
```

**POST, Go**

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"q":"best running shoes"}`)
	req, _ := http.NewRequest("POST", "https://api.bestserp.com/search", body)
	req.Header.Set("X-API-KEY", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

**GET**

```bash
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.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `q` (required) | string |  | Search query (1–256 characters). |
| `gl` | string | us | Country, 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). |
| `hl` | string | en | Interface language (en, vi, de…). |
| `num` | integer | 10 | Maximum 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. |
| `page` | integer | 1 | Page to return, 1–5 (page × num/10 ≤ 5). Pages 1…page are fetched and charged. |
| `tbs` | string |  | Recency: qdr:h (hour), qdr:d (day), qdr:w (week), qdr:m (month), qdr:y (year). Also accepted: timeRange = hour\|day\|week\|month\|year. |
| `resolveLinks` | boolean | true | Replace Google redirect links with final URLs. Results come back at once with linksPending: true; poll the request for final links. |
| `noCache` | boolean | false | Skip the 1-hour result cache (5 minutes for news). |
| `async` | boolean | false | Answer 202 immediately with a requestId to poll. |
| `timeout` | number | 60 | Seconds to wait before answering 202 (1–120). |
| `autocorrect` | boolean |  | Accepted for compatibility; no effect. |

## Response fields

Empty fields are left out of each item.

**`organic[]`**

| Field | Meaning |
| --- | --- |
| `position` | Rank of the result in Google's order, from 1. |
| `title` | Title of the result as Google shows it. |
| `link` | Destination URL. With resolveLinks (the default) Google redirect links are replaced by the final URL; unresolvedLinks counts any that are left. |
| `snippet` | Text shown under the title. |
| `displayedLink` | The URL line as Google displays it, e.g. https://example.com › guides. |
| `source` | Site name shown next to the result. |
| `domain` | Host name of the result, without www. |
| `favicon` | Site icon: a data: URI taken from the page, or a favicon service URL for the domain. |

**`videos[]`**

| Field | Meaning |
| --- | --- |
| `position` | Rank of the video, from 1. |
| `title` | Video title. |
| `link` | Video page URL. |
| `snippet` | Description shown under the title, when there is one. |
| `duration` | Length as displayed, e.g. 12:41. |
| `channel` | Channel or uploader. |
| `platform` | Site hosting the video, e.g. YouTube. |
| `date` | Upload date as displayed. |
| `imageUrl` | Thumbnail as an inline data: URI, only with includeThumbnails: true (about 20 KB each). |

**`news[]`**

| Field | Meaning |
| --- | --- |
| `position` | Rank of the article, from 1. |
| `title` | Headline. |
| `link` | Article URL (Google redirect links are resolved as for web results). |
| `snippet` | Summary shown under the headline, when there is one. |
| `date` | Publish time as displayed, e.g. "2 hours ago" (ISO 8601 when the RSS fallback was used). |
| `publishedAt` | Publish time in ISO 8601 UTC, when it can be determined. |
| `source` | Publisher name. |
| `imageUrl` | Thumbnail as an inline data: URI, only with includeThumbnails: true (about 20 KB each). |
| `domain` | Host name of the article, without www. |
| `favicon` | Publisher icon. |
| `origin` | google_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

| Field | Meaning |
| --- | --- |
| `searchParameters` | Your request after validation, with defaults filled in (q, gl, hl, type, page or pages...). |
| `requestId` | ID of this request. Poll GET /requests/{requestId} for async requests and for final links. |
| `credits` | Credits charged for this request (refunded automatically if it fails). |
| `cached` | true when the answer came from the recent-result cache (1 hour, 5 minutes for news). |
| `linksPending` | true while Google redirect links are being replaced by final URLs; poll the request to get them. |
| `unresolvedLinks` | Links that are still Google redirects: they work, but are not the final URL. |
| `durationMs` | Time the search took, in milliseconds. |
| `ipCountry` | Country 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**

```json
{
  "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](https://bestserp.com/docs/errors).
