Skip to main content

​
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

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 (Paid Plan)

Entity Detection

Identify when suggestions represent specific entities
Rich suggestions with enhanced metadata require a paid subscription. View pricing to unlock these advanced features.

​
API Reference

Suggest API Documentation

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

​
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: 
https://api.search.brave.com/res/v1/suggest/search

​
Getting Started

Get started immediately with a simple cURL request: 
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

{
  "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: 
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

{
  "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

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 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