# Autosuggest

Real-time query autocompletion and suggestions to enhance search experiences

## Overview

Brave Search Autosuggest 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. The suggestions provided are resilient to typos made by the user.

## Key Features

### Real-time Suggestions

Get instant query completions as users type their search queries

### Contextual Results

Suggestions adapt based on country and language preferences

### Rich Enrichments

Enhanced suggestions with titles, descriptions, and images

### Entity Detection

Identify when suggestions represent specific entities

Rich suggestions with enhanced metadata are included with the **Autosuggest plan**. [View pricing](/documentation/pricing) for more details.

## API Reference

### Autosuggest API Documentation

View the complete API reference, including endpoints, parameters, and example requests

## Use Cases

Autosuggest 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 Autosuggest API is available at the following endpoint:

```bash
https://api.search.brave.com/res/v1/suggest/search
```

## Getting Started

Get started immediately with a simple cURL request:

```bash
curl "https://api.search.brave.com/res/v1/suggest/search?q=hello&country=US&count=5" \
  -H "X-Subscription-Token: <YOUR_API_KEY>"
```

### Example Response

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

## Rich Suggestions

With the `rich=true` parameter, suggestions are enhanced with additional metadata:

```bash
curl "https://api.search.brave.com/res/v1/suggest/search?q=einstein&country=US&count=3&rich=true" \
  -H "X-Subscription-Token: <YOUR_API_KEY>"
```

### Enhanced Response Example

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

## Integration Examples

```javascript
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
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 plan's rate limits when designing your integration

## Changelog

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

- **2023-05-01** Add search suggestions endpoint