Rechercher des lieux

L'outil search_places permet à un LLM de trouver des lieux sur Google Maps à partir d'une requête en langage naturel. L'outil renvoie un résumé généré par l'IA des lieux correspondants. Pour chaque lieu cité dans le résumé, il renvoie également l'ID de lieu, les coordonnées, les liens Google Maps et l'attribution.

Cette page décrit les options de requête, y compris les options Pro, le contenu de la réponse et la facturation des requêtes. Pour obtenir le schéma complet de l'outil, consultez la documentation de référence sur search_places.

Options de requête

Le LLM définit ces options lorsqu'il appelle l'outil, en fonction de la requête de l'utilisateur et de la description de l'outil. Vous pouvez influencer les options utilisées par le modèle avec vos propres instructions. Consultez Contrôler l'utilisation de Pro.

Option Description
text_query Obligatoire. Requête de recherche, par exemple coffee shops near Golden Gate Park. La requête doit contenir suffisamment d'informations de localisation pour ne pas être ambiguë, ou inclure location_bias.
location_bias Un cercle (center et radius_meters facultatif, jusqu'à 50 000 mètres) vers lequel orienter les résultats. Si text_query désigne un emplacement explicite, cet emplacement est utilisé à la place.
language_code Langue du résumé, par exemple en ou ja. La langue par défaut est l'anglais.
region_code Code de région CLDR de l'utilisateur, par exemple US. Cela affecte les noms de lieux spécifiques à une région et peut avoir un impact sur les résultats en fonction de la législation applicable.
page_size Nombre maximal de lieux à renvoyer. La valeur par défaut est 5. Les valeurs de 6 à 10 sont une option Pro. Les valeurs supérieures à 10 renvoient une erreur INVALID_ARGUMENT. Le service peut renvoyer moins de lieux que demandé.
include_extended_details Lorsque true, le résumé inclut des informations détaillées sur le lieu. Il s'agit d'une option Pro. La valeur par défaut est false.

Options Pro

Deux options permettent de sélectionner le SKU Pro. Une requête qui utilise l'un ou les deux est facturée sous le SKU Pro :

Option Pro Quand l'utiliser ?
include_extended_details défini sur true La requête de l'utilisateur nécessite des informations détaillées sur le lieu, telles que des insights issus des avis, des plats phares du menu, l'ambiance ou des conseils pour les visiteurs.
page_size de 6 à 10 L'utilisateur souhaite comparer plus de cinq lieux.

Les requêtes qui n'utilisent aucune de ces options, y compris celles dont le paramètre page_size est compris entre 1 et 5, sont facturées selon le SKU Essentials.

Place Details étendu

Définissez include_extended_details sur true lorsque la requête de l'utilisateur nécessite des insights qualitatifs, des conditions en temps réel ou des attributs spécialisés, par exemple :

  • Avis des utilisateurs : insights basés sur les avis, sentiment des clients et commentaires.
  • Offres spécifiques : éléments de menu, plats, spécialités culinaires, boissons ou points forts de l'établissement.
  • Atmosphère : décoration intérieure, esthétique, ambiance ou humeur.
  • Conseils pratiques pour les visiteurs : réservation à l'avance, politique d'accès sans réservation, temps d'attente, affluence, parking et installations.
  • Proximité : distance ou temps de trajet depuis le lieu de la requête ou le centre de location_bias, lorsque l'utilisateur demande ce qui se trouve à proximité ou au plus près.

Les insights d'un résumé dépendent de la requête et des données disponibles pour chaque lieu. Tous les types d'insights n'apparaissent pas dans toutes les réponses.

Laissez la valeur false (par défaut) pour les recherches standards : cuisines ou types de magasins, adresses, coordonnées, horaires d'ouverture et services standards. Les requêtes avec des détails étendus prennent plus de temps.

Les détails étendus ne modifient pas la structure de la réponse. Sans eux, le résumé décrit chaque lieu en une ou deux phrases. Grâce à eux, chaque lieu bénéficie d'une description plus longue qui s'appuie sur davantage de données Google Maps, y compris des insights issus des avis. Les entrées places structurées sont les mêmes pour les deux SKU.

Exemple

La requête suivante demande jusqu'à huit lieux avec des détails étendus. Il est facturé sous le SKU Pro :

{
  "method": "tools/call",
  "params": {
    "name": "search_places",
    "arguments": {
      "text_query": "date night Italian restaurants in Chicago",
      "page_size": 8,
      "include_extended_details": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

Sans détails étendus, le résumé décrit chaque lieu en une ou deux phrases :

Example Trattoria [0] (4,6★ (1 250) · 123 W Example St · $$$) A neighborhood trattoria known for handmade pasta and a long wine list.

With extended details, the summary adds what reviewers highlight and practical tips:

Example Trattoria [0] (4.6★ (1,250) · 123 W Example St · $$$) Une salle à manger intimiste éclairée à la bougie, que les clients décrivent comme romantique, mais bruyante le week-end. Les tagliatelles al ragù, la burrata et le tiramisu sont des plats incontournables. Il est recommandé de réserver. Les clients sans réservation peuvent s'attendre à une attente de 30 à 45 minutes les vendredis et samedis soir, et le stationnement sur rue est limité.

Réponse

La réponse contient les éléments suivants :

  • summary : résumé en langage naturel des résultats de recherche. Il peut contenir des citations commençant par zéro, telles que [0], qui correspondent à des entrées dans places.
  • places[] : lieux mentionnés dans le résumé. Chaque lieu inclut :
    • place : nom de ressource du lieu, au format places/{id}.
    • id : ID de lieu. Vous pouvez l'utiliser avec d'autres API Google Maps Platform, par exemple pour afficher le lieu sur une carte.
    • location : latitude et longitude du lieu.
    • googleMapsLinks : liens Google Maps vers le lieu (placeUrl), l'itinéraire (directionsUrl), les avis (reviewsUrl), les photos (photosUrl) et la rédaction d'un avis (writeAReviewUrl).
    • attribution : mention que vous devez afficher avec le lieu. Consultez Exigences d'attribution.

La réponse a la même structure pour les deux SKU. Pour en savoir plus sur les champs, consultez la documentation de référence sur search_places.

Options Pro pendant la disponibilité générale restreinte

Pendant la disponibilité générale restreinte, les options Pro ne sont disponibles que pour les projets figurant sur la liste d'autorisation Pro. Si votre projet ne figure pas encore sur la liste d'autorisation, les options Pro sont ignorées plutôt que rejetées :

  • include_extended_details est traité comme false.
  • Les valeurs page_size supérieures à 5, y compris celles supérieures à 10, sont réduites à 5.

La requête est facturée sous le SKU Essentials. Pour demander l'accès, consultez Options Pro pendant la disponibilité générale restreinte.

Facturation et quotas

Chaque requête search_places correspond à un événement facturable :

Le quota de search_places est de 300 requêtes par minute et par projet, partagé par les deux SKU. Pour connaître les tarifs, consultez la grille tarifaire principale et la grille tarifaire pour l'Inde.