Suggestions / Autocomplétion

Clé API requise : Obtenez-en une à https://api.search.brave.com

Plan : Inclus dans le plan Suggest. Voir https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Démarrage rapide (cURL)

Suggestions de base

curl -s "https://api.search.brave.com/res/v1/suggest/search?q=how+to+" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

Avec tous les paramètres

curl -s "https://api.search.brave.com/res/v1/suggest/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=albert" \
  --data-urlencode "country=US" \
  --data-urlencode "lang=en" \
  --data-urlencode "count=10" \
  --data-urlencode "rich=true"

Endpoint

GET https://api.search.brave.com/res/v1/suggest/search

Authentification : en-tête X-Subscription-Token: <API_KEY>

En-têtes optionnels :

Accept-Encoding: gzip — Activer la compression de réponse

Paramètres

Paramètre	Type	Requis	Par défaut	Description
`q`	string	Oui	—	Requête de suggestion (1-400 caractères, max 50 mots)
`lang`	string	Non	`en`	Préférence de langue (code langue 2+ caractères, ex. `fr`, `de`, `zh-hans`)
`country`	string	Non	`US`	Pays de recherche (code pays 2 lettres ou `ALL`)
`count`	int	Non	`5`	Nombre de suggestions (1-20). Les résultats réels peuvent être moins nombreux
`rich`	bool	Non	`false`	Enrichir avec info entité (titre, description, image). Plan Search payant requis

Champs de réponse

Champ	Type	Description
`type`	string	Toujours `"suggest"`
`query.original`	string	La requête de suggestion d'origine
`results`	array	Liste de suggestions (peut être vide)
`results[].query`	string	Complément de requête suggéré
`results[].is_entity`	bool?	Si la requête enrichie suggérée est une entité (rich uniquement)
`results[].title`	string?	Titre enrichi de la requête suggérée (rich uniquement)
`results[].description`	string?	Description enrichie de la requête suggérée (rich uniquement)
`results[].img`	string?	URL d'image enrichie de la requête suggérée (rich uniquement)

Les champs avec valeurs null sont exclus de la réponse. Les résultats non-rich contiennent uniquement le champ query.

Exemple de réponse enrichie (`rich=true`)

{
  "type": "suggest",
  "query": { "original": "albert" },
  "results": [
    {
      "query": "albert einstein",
      "is_entity": true,
      "title": "Albert Einstein",
      "description": "German-born theoretical physicist",
      "img": "https://imgs.search.brave.com/..."
    },
    { "query": "albert einstein quotes", "is_entity": false }
  ]
}

Cas d'usage

Search-as-you-type UI : Autocomplétion temps réel dans une liste déroulante. Débouncer 150-300 ms.
Affinage de requête pour RAG : Élargir requêtes partielles/ambiguës avant appel à web-search ou llm-context.
Détection d'entité : Utiliser rich=true pour détecter entités avec titre, description et image pour cartes d'aperçu.
Entrée tolérant les fautes : Obtenir suggestions nettoyées d'entrée mal orthographiée sans spellcheck séparé.

Remarques

Latence : Conçu pour des temps de réponse < 100 ms
Pays/langue : Indications pour pertinence des suggestions, pas filtres stricts
Gestion des fautes : Suggestions gèrent les fautes courantes sans spellcheck séparé