> ## Documentation Index
> Fetch the complete documentation index at: https://test-62a57ffd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Suggest

> Real-time query autocompletion and suggestions to enhance search experiences

## Overview

Brave Search Suggest API provides intelligent query autocompletion and search suggestions as users type, helping them formulate better queries and discover relevant content faster. The API returns contextually relevant suggestions based on the partial query input, with optional enrichment data for enhanced user experiences.

## Key Features

<CardGroup cols={2}>
  <Card title="Real-time Suggestions" icon="wand-magic-sparkles">
    Get instant query completions as users type their search queries
  </Card>

  <Card title="Contextual Results" icon="globe">
    Suggestions adapt based on country and language preferences
  </Card>

  <Card title="Rich Enrichments" icon="sparkles">
    Enhanced suggestions with titles, descriptions, and images **(Paid Plan)**
  </Card>

  <Card title="Entity Detection" icon="tag">
    Identify when suggestions represent specific entities
  </Card>
</CardGroup>

<Note>
  Rich suggestions with enhanced metadata require a **paid subscription**. [View
  pricing](/pricing) to unlock these advanced features.
</Note>

## API Reference

<Card title="Suggest API Documentation" icon="code" href="/api-reference/suggest/search">
  View the complete API reference, including endpoints, parameters, and example
  requests
</Card>

## Use Cases

Suggest API is perfect for:

* **Search Boxes**: Power autocomplete in search interfaces
* **User Experience**: Help users formulate better queries faster
* **Query Refinement**: Guide users toward popular or relevant searches
* **Content Discovery**: Surface trending or related topics as users type
* **Mobile Applications**: Provide touch-friendly query suggestions

## Endpoint

Brave Suggest API is available at the following endpoint:

```bash theme={null}
https://api.search.brave.com/res/v1/suggest/search
```

## Getting Started

Get started immediately with a simple cURL request:

```bash theme={null}
curl -s --compressed "https://api.search.brave.com/res/v1/suggest/search?q=hello&country=US&count=5" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: <YOUR_API_KEY>"
```

### Example Response

```json theme={null}
{
  "type": "suggest",
  "query": {
    "original": "hello"
  },
  "results": [
    {
      "query": "hello world"
    },
    {
      "query": "hello kitty"
    },
    {
      "query": "hello neighbor"
    },
    {
      "query": "hello fresh"
    },
    {
      "query": "hello sunshine"
    }
  ]
}
```

## Rich Suggestions

With a paid subscription and the `rich=true` parameter, suggestions are enhanced with additional metadata:

```bash theme={null}
curl -s --compressed "https://api.search.brave.com/res/v1/suggest/search?q=einstein&country=US&count=3&rich=true" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: <YOUR_API_KEY>"
```

### Enhanced Response Example

```json theme={null}
{
  "type": "suggest",
  "query": {
    "original": "einstein"
  },
  "results": [
    {
      "query": "albert einstein",
      "is_entity": true,
      "title": "Albert Einstein",
      "description": "Theoretical physicist who developed the theory of relativity",
      "img": "https://example.com/einstein.jpg"
    },
    {
      "query": "einstein theory",
      "is_entity": false
    },
    {
      "query": "einstein quotes"
    }
  ]
}
```

## Integration Examples

### JavaScript/TypeScript

```javascript theme={null}
async function getSuggestions(query) {
  const params = new URLSearchParams({
    q: query,
    country: "US",
    count: "10",
    rich: "true",
  });

  const response = await fetch(
    `https://api.search.brave.com/res/v1/suggest/search?${params}`,
    {
      headers: {
        Accept: "application/json",
        "Accept-Encoding": "gzip",
        "X-Subscription-Token": "YOUR_API_KEY",
      },
    }
  );

  return await response.json();
}

// Usage
const suggestions = await getSuggestions("brave search");
console.log(suggestions.results);
```

### Python

```python theme={null}
import requests

def get_suggestions(query: str, count: int = 5, rich: bool = False):
    url = "https://api.search.brave.com/res/v1/suggest/search"

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

    params = {
        "q": query,
        "country": "US",
        "count": count,
        "rich": rich
    }

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

# Usage
suggestions = get_suggestions("brave search", count=10, rich=True)
for result in suggestions["results"]:
    print(result["query"])
```

## Best Practices

### Performance Optimization

* **Debounce Requests**: Implement debouncing (e.g., 150-300ms) to avoid excessive API calls as users type
* **Progressive Enhancement**: Load suggestions asynchronously without blocking the UI

### Rate Limiting

* Only make requests after users pause typing (debouncing)
* Implement client-side caching for repeated queries
* Consider your subscription plan's rate limits when designing your integration

## Changelog

This changelog outlines all significant changes to the Brave Search Suggest API in chronological order.

### 2023-05-01

* Initial launch of Brave Search Suggest API
* Add search suggestions endpoint