Recherche Web

Clé API requise : Obtiens-en une sur https://api.search.brave.com

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

Démarrage rapide (cURL)

Recherche basique

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

Avec paramètres

curl -s "https://api.search.brave.com/res/v1/web/search" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=rust programming tutorials" \
  --data-urlencode "country=US" \
  --data-urlencode "search_lang=en" \
  --data-urlencode "count=10" \
  --data-urlencode "safesearch=moderate" \
  --data-urlencode "freshness=pm"

Endpoint

GET https://api.search.brave.com/res/v1/web/search
POST https://api.search.brave.com/res/v1/web/search

Remarque : Les méthodes GET et POST sont toutes deux supportées. POST est utile pour les requêtes longues ou les Goggles complexes.

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

En-têtes optionnels :

• Accept-Encoding: gzip — Activer la compression gzip

Quand utiliser la recherche Web

Paramètres

Valeurs de Freshness

Valeurs de Result Filter

Types de filtre : discussions, faq, infobox, news, query, videos, web, locations

# Uniquement résultats web et vidéo
curl "...&result_filter=web,videos"

En-têtes de localisation (Optionnels)

Pour des résultats conscients de la localisation, ajoute ces en-têtes. Lat/Long suffit quand les coordonnées sont connues — les autres en-têtes ne sont nécessaires qu'en secours quand les coordonnées ne sont pas disponibles.

Priorité : X-Loc-Lat + X-Loc-Long prennent le dessus. Quand fournis, les services en aval résolvent la localisation directement à partir des coordonnées et les en-têtes textuels (City, State, Country, Postal-Code) ne sont pas utilisés pour la résolution de localisation. Fournis les en-têtes textuels uniquement quand tu n'as pas de coordonnées. Envoyer les deux ne causera aucun problème — lat/long gagne simplement.

Format de réponse

Champs de réponse

Exemple JSON

{
  "type": "search",
  "query": {
    "original": "python frameworks",
    "altered": "python web frameworks",
    "spellcheck_off": false,
    "more_results_available": true
  },
  "web": {
    "type": "search",
    "results": [
      {
        "title": "Top Python Web Frameworks",
        "url": "https://example.com/python-frameworks",
        "description": "A comprehensive guide to Python web frameworks...",
        "age": "2 days ago",
        "language": "en",
        "meta_url": {
          "scheme": "https",
          "netloc": "example.com",
          "hostname": "example.com",
          "path": "/python-frameworks"
        },
        "thumbnail": {
          "src": "https://...",
          "original": "https://original-image-url.com/img.jpg"
        },
        "extra_snippets": ["Additional excerpt 1...", "Additional excerpt 2..."]
      }
    ],
    "family_friendly": true
  },
  "mixed": {
    "type": "mixed",
    "main": [
      {"type": "web", "index": 0, "all": false},
      {"type": "web", "index": 1, "all": false},
      {"type": "videos", "all": true}
    ],
    "top": [],
    "side": []
  },
  "videos": { "...": "..." },
  "news": { "...": "..." },
  "rich": {
    "type": "rich",
    "hint": {
      "vertical": "weather",
      "callback_key": "<callback_key_hex>"
    }
  }
}

Réponse mixte

L'objet mixed définit l'ordre d'affichage préféré des résultats à travers les types. Il contient trois tableaux :

Chaque entrée est une ResultReference avec type (ex. "web", "videos"), index (dans le tableau de résultats correspondant), et all (true pour inclure tous les résultats de ce type à cette position).

Opérateurs de recherche

Définis operators=false pour désactiver l'analyse des opérateurs.

Goggles (Classement personnalisé) — Unique à Brave

Les Goggles te permettent de réclasser les résultats de recherche — amplifier sources de confiance, supprimer spam SEO, ou construire scopes de recherche ciblés.

Les Goggles hébergés doivent être sur GitHub/GitLab, inclure en-têtes ! name:, ! description:, ! author:, et être enregistrés sur https://search.brave.com/goggles/create. Les règles inline ne nécessitent aucune inscription.

Syntaxe : $boost=N / $downrank=N (1–10), $discard, $site=example.com. Combiner avec virgules : $site=example.com,boost=3. Séparer règles avec \n (%0A).

Liste blanche : $discard\n$site=docs.python.org\n$site=developer.mozilla.org — Liste noire : $discard,site=pinterest.com\n$discard,site=quora.com

Ressources : Discover · Syntaxe · Quickstart

Enrichissements de données enrichies

Pour requêtes sur météo, actions, sports, devises, etc., utilise le workflow callback enrichi :

# 1. Rechercher avec callback enrichi activé
curl -s "https://api.search.brave.com/res/v1/web/search?q=weather+san+francisco&enable_rich_callback=true" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

# Réponse inclut : "rich": {"hint": {"callback_key": "abc123...", "vertical": "weather"}}

# 2. Obtenir données enrichies avec la clé callback
curl -s "https://api.search.brave.com/res/v1/web/rich?callback_key=abc123..." \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

Types enrichis supportés : Calculator, Definitions, Unit Conversion, Unix Timestamp, Package Tracker, Stock, Currency, Cryptocurrency, Weather, American Football, Baseball, Basketball, Cricket, Football/Soccer, Ice Hockey, Web3, Translator

Endpoint Callback enrichi

GET https://api.search.brave.com/res/v1/web/rich

Cas d'usage

• Intégration de recherche généraliste : Ensemble de résultats le plus riche (web, actualités, vidéos, discussions, FAQ, infobox, lieux) en un appel. Pour ancrage RAG/LLM, préfère llm-context.
• Extraction de données structurées : Produits, recettes, notes, articles via schemas et champs typés sur résultats.
• Recherche personnalisée avec Goggles : Unique à Brave. Amplifier/ignorer sites avec règles inline ou Goggles hébergés pour classement entièrement personnalisé.

Notes

• Pagination : Utilise offset (0–9) avec count pour parcourir résultats
• Count : Max 20 pour recherche web ; résultats réels peuvent être moins que demandé