Descriptions locales (API Search)

Nécessite une clé API : obtenez-en une sur https://api.search.brave.com

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

Flux en deux étapes : cet endpoint nécessite des identifiants POI d'une recherche web antérieure.

Appelez web-search avec result_filter=locations pour obtenir les identifiants POI depuis locations.results[].id

Transmettez ces identifiants à cet endpoint pour obtenir des descriptions générées par IA

Démarrage rapide (cURL)

Obtenir la description d'un POI

curl -s "https://api.search.brave.com/res/v1/local/descriptions?ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA%3D" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

Plusieurs POIs

curl -s "https://api.search.brave.com/res/v1/local/descriptions" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=" \
  --data-urlencode "ids=loc4HTAVTJKP4RBEBZCEMBI3NG26YD4II4PATIHPDYI="

Note : les identifiants POI sont des chaînes opaques retournées dans la recherche web locations.results[].id. Ils sont valides pendant environ 8 heures. Les identifiants d'exemple ci-dessus sont fournis à titre d'illustration — récupérez des identifiants frais via web-search avec result_filter=locations.

Endpoint

GET https://api.search.brave.com/res/v1/local/descriptions

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

Paramètres

Paramètre	Type	Obligatoire	Défaut	Description
`ids`	string[]	Oui	—	Identifiants POI de la recherche web `locations.results[].id` (1-20, répétés : `?ids=a&ids=b`)

Format de réponse

Champs de réponse

Champ	Type	Description
`type`	string	Toujours `"local_descriptions"`
`results`	array	Liste d'objets description (les entrées peuvent être `null`)
`results[].type`	string	Toujours `"local_description"`
`results[].id`	string	Identifiant POI correspondant à la requête
`results[].description`	string?	Description markdown générée par IA, ou `null` si indisponible

Exemple de réponse

{
  "type": "local_descriptions",
  "results": [
    {
      "type": "local_description",
      "id": "loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=",
      "description": "### Overview\nA cozy neighborhood cafe known for its **artisanal coffee**..."
    }
  ]
}

Obtention des identifiants POI

Les identifiants POI proviennent de l'API Web Search (web-search) avec result_filter=locations :

# 1. Rechercher des commerces locaux
curl -s "https://api.search.brave.com/res/v1/web/search?q=restaurants+san+francisco&result_filter=locations" \
  -H "Accept: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

# 2. Extraire les identifiants POI de locations.results[].id
# 3. Utiliser ces identifiants avec local/pois et local/descriptions

Cas d'usage

Aperçu des commerces locaux : combinez avec local-pois pour obtenir à la fois des données structurées (horaires, évaluations) et des descriptions narratives
Enrichissement voyage/tourisme : ajouter du contexte descriptif aux POIs pour la planification de voyages ou les guides touristiques
Augmentation des résultats de recherche : compléter les résultats de recherche web avec des résumés générés par IA de commerces locaux

Notes

Toujours en markdown : les descriptions utilisent des en-têtes ###, des listes à puces, du gras/italiques — toujours formatées en markdown
Ton de guide touristique : généralement 200-400 mots couvrant ce qui rend le POI remarquable
Généré par IA : les descriptions sont générées par IA basées sur le contexte de recherche web, non extraites de profils commerciaux
Disponibilité : tous les POIs n'ont pas de descriptions — description peut être null
Identifiants max : jusqu'à 20 identifiants par requête

local-descriptions