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

Key Features

API Reference

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 "https://api.search.brave.com/res/v1/suggest/search?q=hello&country=US&count=5" \
  -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 "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

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

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

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 Add search suggestions endpoint