Recherche de lieux (API Search)

Nécessite une clé API : Obtenir une à https://api.search.brave.com

Plan : Inclus dans le plan Search (avec l'option locations). Voir https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Autonome : Contrairement à local-pois et local-descriptions, cet endpoint ne nécessite pas d'identifiants POI d'une recherche web préalable. Vous fournissez directement un lieu et une requête optionnelle.

Démarrage rapide (cURL)

Recherche par requête + coordonnées

curl -s "https://api.search.brave.com/res/v1/local/place_search" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=coffee shops" \
  --data-urlencode "latitude=37.7749" \
  --data-urlencode "longitude=-122.4194" \
  --data-urlencode "radius=5000"

Recherche par requête + chaîne de lieu

curl -s "https://api.search.brave.com/res/v1/local/place_search" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "q=sushi restaurants" \
  --data-urlencode "location=tokyo japan" \
  --data-urlencode "country=JP" \
  --data-urlencode "search_lang=en"

Parcourir les POI généraux (sans requête)

curl -s "https://api.search.brave.com/res/v1/local/place_search" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -G \
  --data-urlencode "latitude=48.8566" \
  --data-urlencode "longitude=2.3522" \
  --data-urlencode "radius=3000" \
  --data-urlencode "country=FR"

Endpoint

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

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

Paramètres

Lieu (optionnel mais recommandé)

Fournir une ancre géographique améliore la précision. Vous pouvez utiliser des coordonnées (latitude + longitude) ou une chaîne location. Omettre les deux est autorisé quand une q est fournie — les résultats sont issus mondialement et peuvent être moins précis. Omettre les trois (q, latitude/longitude, et location) renvoie HTTP 422.

Recherche

Options supplémentaires

Format de réponse

Champs de niveau supérieur

Traitez un bucket manquant comme vide. Pour les requêtes de style POI typiques, seul results est rempli, donc les clients qui ne restituent pas des SERP riches peuvent ignorer le reste — sauf pour les requêtes en forme d'adresse ou de rue, qui peuvent retourner results vide et placer chaque correspondance dans addresses/streets.

Champs LocationResult

Chaque élément de results est un LocationResult :

Champs de lieu géographique (cities, countries, regions, neighborhoods)

Les quatre buckets partagent une même structure, différant seulement par l'identifiant type. La spec publiée les nomme CityResult / CountryResult / RegionResult / NeighborhoodResult.

Champs AddressResult (addresses et streets)

Le même modèle est utilisé pour les deux buckets. Les éléments de addresses ont type: "address" (rue + numéro) ; les éléments de streets ont type: "street" (rue entière).

Ordonnancement mixte (mixed)

mixed est une liste ordonnée d'objets ResultReference indiquant aux clients comment entrelacer les éléments des différents buckets sur un seul SERP.

Les clients qui restituent seulement des POI peuvent ignorer mixed entièrement et lire results directement.

Exemple de réponse

{
  "type": "locations",
  "results": [
    {
      "type": "location_result",
      "title": "Blue Bottle Coffee",
      "url": "https://yelp.com/biz/blue-bottle-coffee-sf",
      "provider_url": "",
      "id": "loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=",
      "description": "Coffee Shop",
      "postal_address": {
        "type": "PostalAddress",
        "displayAddress": "315 Linden St, San Francisco, CA 94102"
      },
      "contact": { "telephone": "+15106533394" },
      "rating": {
        "ratingValue": 4.3,
        "bestRating": 5.0,
        "reviewCount": 1024,
        "is_tripadvisor": true
      },
      "opening_hours": {
        "current_day": [
          { "abbr_name": "Tue", "full_name": "Tuesday", "opens": "07:00", "closes": "18:00" }
        ],
        "days": [
          [{ "abbr_name": "Mon", "full_name": "Monday", "opens": "07:00", "closes": "18:00" }]
        ]
      },
      "coordinates": [37.7763, -122.4215],
      "categories": [],
      "serves_cuisine": ["Cafe", "Coffee Shop"],
      "price_range": "$$",
      "icon_category": "cafe",
      "thumbnail": {
        "src": "https://example.com/thumb.jpg",
        "original": "https://example.com/original.jpg"
      },
      "zoom_level": 7
    }
  ],
  "cities": [],
  "countries": [],
  "regions": [],
  "neighborhoods": [],
  "addresses": [],
  "streets": [],
  "mixed": [
    { "type": "results", "index": 0, "all": false }
  ],
  "location": {
    "coordinates": [37.7749, -122.4194],
    "name": "San Francisco",
    "country": "US"
  }
}

Pour une requête qui correspond à un nom de ville, la réponse ajoute une entrée city dans cities :

{
  "cities": [
    {
      "type": "city",
      "name": "San Francisco",
      "country": "US",
      "coordinates": [37.7749, -122.4194],
      "thumbnail": { "src": "https://example.com/sf.jpg" }
    }
  ],
  "mixed": [
    { "type": "cities", "index": 0, "all": false }
  ]
}

Enrichir les résultats avec les détails POI et les descriptions

Les valeurs id POI de results peuvent être transmises aux endpoints frères pour des données plus riches :

# Obtenir les détails complets du POI (heures, avis, photos, mentions de résultats web)
curl -s "https://api.search.brave.com/res/v1/local/pois" -G \
  --data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

# Obtenir les descriptions générées par IA
curl -s "https://api.search.brave.com/res/v1/local/descriptions" -G \
  --data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}"

Cas d'usage

• Exploration basée sur carte : Rechercher des POI dans une fenêtre de carte visible en utilisant des coordonnées + rayon. Aucune requête préalable nécessaire.
• Applications géolocalisées : Construire des fonctionnalités « À proximité » — transmettre les coordonnées GPS de l'appareil et une requête pour trouver des entreprises pertinentes.
• Planification de voyage : Rechercher des attractions, restaurants et hôtels par chaîne de lieu (ex. paris france) sans avoir besoin de coordonnées exactes.

Notes

• Trouve des lieux, pas des pages : Cet endpoint recherche dans un index géographique de lieux physiques. Utilisez la recherche web pour la récupération d'informations générales.
• Choisir un rayon : Un rayon plus serré (sous ~20 km) donne des résultats plus focalisés. Augmentez-le pour atteindre des lieux spécifiques ou bien connus plus loin ; pour les recherches de catégories courantes (ex. restaurants), le biais par défaut ou plus serré fonctionne mieux.