# Suggestions

`GET` `/v1/suggest/search`

Intelligent search suggestions to help users find what they’re looking for.

**Base URL:** `https://api.search.brave.com/res`

## Authorization

| Name | Location | Type | Required | Constraints | Description |
|------|----------|------|----------|-------------|-------------|
| `x-subscription-token` | header | string | Yes |  | The subscription token that was generated for the product. |

## Query Parameters

| Name | Location | Type | Required | Constraints | Description |
|------|----------|------|----------|-------------|-------------|
| `q` | query | string | Yes |  | The user's suggest search query term. Query can not be empty. The max query length is 400 characters, and the word limit is 50 words. |
| `lang` | query | string | No | `ar`, `eu`, `bn`, `bg`, `ca`, `zh-hans`, `zh-hant`, `hr`, `cs`, `da`, `nl`, `en`, `en-gb`, `et`, `fi`, `fr`, `gl`, `de`, `el`, `gu`, `he`, `hi`, `hu`, `is`, `it`, `ja`, `jp`, `kn`, `ko`, `lv`, `lt`, `ms`, `ml`, `mr`, `nb`, `pl`, `pt-br`, `pt-pt`, `pa`, `ro`, `ru`, `sr`, `sk`, `sl`, `es`, `sv`, `ta`, `te`, `th`, `tr`, `uk`, `vi`; default `en` | The suggest search language preference, where potentially the results could come from. The 2 or more character language code for which the suggest search results are provided. This is a just a hint for calculating suggest responses. |
| `country` | query | string | No | `AR`, `AU`, `AT`, `BE`, `BR`, `CA`, `CL`, `DK`, `FI`, `FR`, `DE`, `GR`, `HK`, `IN`, `ID`, `IT`, `JP`, `KR`, `MY`, `MX`, `NL`, `NZ`, `NO`, `CN`, `PL`, `PT`, `PH`, `RU`, `SA`, `ZA`, `ES`, `SE`, `CH`, `TW`, `TR`, `GB`, `US`, `ALL`; default `US` | The suggest search query country, where potentially the results could come from. The country string is limited to 2 character country codes of supported countries. This is a just a hint for calculating suggest responses. |
| `count` | query | integer | No | `1`-`20`; default `5` | The number of suggestion search results returned in response. The actual number of results delivered may be less than requested. Minimum is 1, maximum is 20. The default is 5. |
| `rich` | query | boolean | No | default `false` | Whether to enhance suggestions with rich results. This requires a paid autosuggest subscription. |

## Headers

| Name | Location | Type | Required | Constraints | Description |
|------|----------|------|----------|-------------|-------------|
| `api-version` | header | string | No |  | The API version to use. This is denoted by the format `YYYY-MM-DD`. Default is the latest that is available. Read more about [API versioning](/documentation/guides/versioning). |
| `accept` | header | string | No | `application/json`, `*/*`; default `application/json` | The default supported media type is application/json. |
| `cache-control` | header | string | No | `no-cache` | Brave Search will return cached content by default. To prevent caching set the Cache-Control header to `no-cache`. This is currently done as best effort. |
| `user-agent` | header | string | No |  | The user agent originating the request. Brave search can utilize the user agent to provide a different experience depending on the device as described by the string. The user agent should follow the commonly used browser agent strings on each platform. For more information on curating user agents, see [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-user-agent). |

## Responses

### 200
Successful Response

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `query` | object | Suggest search query string. Only the original query is returned. |
| `query.original` | string | The original query that was requested. |
| `results` | object[]? | The list of suggestions for the given query. |
| `results[].query` | string | Suggested query completion. |
| `results[].type` | string? | Kind of suggestion, currently `query` or `entity`. New kinds may be added, so treat an unrecognised value as a plain query suggestion. |
| `results[].is_entity` | bool? | Whether the suggested enriched query is an entity. Deprecated: use `type` instead. |
| `results[].title` | string? | The suggested query enriched title. |
| `results[].description` | string? | The suggested query enriched description. |
| `results[].img` | string? | The suggested query enriched image URL. |

### 404
Not Found

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `error` | object |  |
| `error.id` | string | A unique identifier for this particular occurrence of the problem. |
| `error.status` | int | The HTTP status code applicable to this problem, expressed as a string value. |
| `error.detail` | string? | Explanation specific to this occurrence of the problem. Like title, this field's value can be localized. |
| `error.meta` | object? | A meta object containing non-standard meta-information about the error. |
| `error.code` | string | An application-specific error code, expressed as a string value. |
| `time` | int? |  |

### 422
Unprocessable Entity

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `error` | object |  |
| `error.id` | string | A unique identifier for this particular occurrence of the problem. |
| `error.status` | int | The HTTP status code applicable to this problem, expressed as a string value. |
| `error.detail` | string? | Explanation specific to this occurrence of the problem. Like title, this field's value can be localized. |
| `error.meta` | object? | A meta object containing non-standard meta-information about the error. |
| `error.code` | string | An application-specific error code, expressed as a string value. |
| `time` | int? |  |

### 429
Too Many Requests

| Field | Type | Description |
|-------|------|-------------|
| `type` | string? |  |
| `error` | object |  |
| `error.id` | string | A unique identifier for this particular occurrence of the problem. |
| `error.status` | int | The HTTP status code applicable to this problem, expressed as a string value. |
| `error.detail` | string? | Explanation specific to this occurrence of the problem. Like title, this field's value can be localized. |
| `error.meta` | object? | A meta object containing non-standard meta-information about the error. |
| `error.code` | string | An application-specific error code, expressed as a string value. |
| `time` | int? |  |

## Code Samples

### cURL

```bash
curl "https://api.search.brave.com/res/v1/suggest/search?q=how+to+" \
  -H "Accept: application/json" \ 
  -H "Accept-Encoding: gzip" \ 
  -H "X-Subscription-Token: <YOUR_API_KEY>"
```

### Python

```python
import requests

url = "https://api.search.brave.com/res/v1/suggest/search"

params = {
    "q": "how to "
}

headers = {
    "Accept": "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": "<YOUR_API_KEY>"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())
```