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 de latitude/longitude, les liens Google Maps et l'attribution.
Vous pouvez appeler search_places via le serveur MCP ou en tant que méthode REST searchText. 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 les schémas complets, consultez la documentation de référence sur le MCP search_places et la documentation de référence sur REST searchText.
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.
Le tableau suivant décrit les options de requête pour search_places :
| Option | Description |
|---|---|
text_query |
Obligatoire. La 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) pour affiner 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 valeur 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 sélectionnent le SKU Maps Grounding Pro. Une requête qui utilise l'une ou l'autre de ces fonctionnalités est facturée au 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 de 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 avec un page_size compris entre 1 et 5, sont facturées au SKU Essentials.
Place Details (Advanced)
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 l'emplacement 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 par défaut false pour les recherches standards : types de cuisine ou de magasin, 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 informations issues des avis. Les entrées places structurées sont les mêmes pour les deux SKU.
Exemple
La requête MCP suivante demande jusqu'à huit lieux avec des informations détaillées. 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
}
L'exemple suivant envoie la même requête à la méthode REST searchText :
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
"textQuery": "date night Italian restaurants in Chicago",
"pageSize": 8,
"includeExtendedDetails": true
}' \
"https://mapstools.googleapis.com/v1:searchText"
Remplacez API_KEY par votre clé API.
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. Le stationnement dans la rue est limité.
Réponse
La réponse contient les champs suivants :
summary: résumé en langage naturel des résultats de recherche. Il peut contenir des citations basées sur zéro, telles que[0], qui correspondent à des entrées dansplaces.places[]: lieux mentionnés dans le résumé. Chaque lieu inclut :place: nom de ressource du lieu, au formatplaces/{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: coordonnées de latitude/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: attribution que vous devez afficher avec le lieu. Consultez Exigences d'attribution.
contentToken: jeton de visualisation des données agentique (preview) qui vous permet d'afficher les lieux de la réponse avec le kit UI pour Places sans frais supplémentaires. Renvoyé lorsque la réponse inclut au moins un lieu.
La réponse a la même structure pour les deux SKU, ainsi que pour MCP et REST. Pour en savoir plus sur les champs, consultez la documentation de référence sur search_places.
Facturation et quotas
Chaque requête search_places correspond à un événement facturable :
- Une requête qui n'utilise aucune option Pro est facturée sous le SKU Maps Grounding Essentials.
- Une requête qui utilise une option Pro est facturée sous le SKU Maps Grounding Pro. L'utilisation des deux options dans une même requête ne modifie pas les frais. Pour connaître les tarifs de l'édition Pro, consultez Comparer les éditions Essentials, Pro et l'ancrage avec Google Maps.
Si vous affichez les lieux d'une réponse search_places avec le Kit UI pour Places, vous pouvez utiliser le jeton de visualisation des données agentique (preview) afin que ces requêtes du Kit UI pour Places ne soient pas facturées.
Le quota search_places est de 300 requêtes par minute pour chaque projet, partagé par les deux SKU. Pour connaître les tarifs, consultez la grille tarifaire principale et la grille tarifaire pour l'Inde.