Une requête Nearby Search (New) prend un ou plusieurs types de lieux et renvoie une liste de lieux correspondants dans la zone spécifiée. Un masque de champ spécifiant un ou plusieurs types de données est requis. Nearby Search (nouveau) n'accepte que les requêtes POST.
APIs Explorer vous permet d'envoyer des requêtes en direct afin que vous puissiez vous familiariser avec l'API et ses options:
EssayerEssayez la démonstration interactive pour voir les résultats de Nearby Search (nouveau) affichés sur une carte.
Requêtes Nearby Search (nouvelle version)
Une requête Nearby Search (New) est une requête HTTP POST adressée à une URL au format suivant:
https://places.googleapis.com/v1/places:searchNearby
Transmettez tous les paramètres dans le corps de la requête JSON ou dans les en-têtes dans la requête POST. Exemple :
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Réponses Nearby Search (nouvelle)
Nearby Search (nouveau) renvoie un objet JSON en tant que réponse. Dans la réponse :
- Le tableau
places
contient tous les lieux correspondants. - Chaque lieu dans le tableau est représenté par un objet
Place
. L'objetPlace
contient des informations détaillées sur un seul lieu. - Le paramètre FieldMask transmis dans la requête spécifie la liste des champs renvoyés dans l'objet
Place
.
L'objet JSON complet se présente sous la forme suivante:
{ "places": [ { object (Place) } ] }
Paramètres obligatoires
-
FieldMask
Spécifiez la liste des champs à renvoyer dans la réponse en créant un masque de champ de réponse. Transmettez le masque de champ de réponse à la méthode à l'aide du paramètre d'URL
$fields
oufields
, ou de l'en-tête HTTPX-Goog-FieldMask
. Il n'existe pas de liste par défaut des champs renvoyés dans la réponse. Si vous omettez le masque de champ, la méthode renvoie une erreur.Le masquage de champ est une bonne pratique à suivre pour vous assurer de ne pas demander de données inutiles, ce qui permet d'éviter le temps de traitement et les frais facturés.
Spécifiez une liste de types de données de lieu à renvoyer, séparés par une virgule. Par exemple, pour récupérer le nom à afficher et l'adresse du lieu.
X-Goog-FieldMask: places.displayName,places.formattedAddress
Utilisez
*
pour récupérer tous les champs.X-Goog-FieldMask: *
Renseignez un ou plusieurs des champs suivants:
Les champs suivants déclenchent le SKU Nearby Search (Basic):
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.attributions
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.adrFormatAddress
,places.adrFormatAddress
dans le champplaces.adrFormatAddress
,places.adrFormatAddress
places.name
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
Utilisezplaces.displayName
pour accéder au nom textuel du lieu.Les champs suivants déclenchent le SKU Nearby Search (Advanced):
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
Les champs suivants déclenchent le SKU Nearby Search (Preferred):
places.allowsDogs
,places.curbsidePickup
,places.delivery
,places.dineIn
,places.editorialSummary
,places.evChargeOptions
,places.fuelOptions
,places.goodForChildren
,places.goodForGroups
,places.goodForWatchingSports
,places.liveMusic
,places.menuForChildren
,places.parkingOptions
,places.paymentOptions
,places.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.servesBeer
,places.delivery
,places.delivery
,places.delivery
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
Région dans laquelle effectuer la recherche, spécifiée sous la forme d'un cercle, définie par le point central et le rayon en mètres. Le rayon doit être compris entre 0,0 et 50 000,0 inclus. Le rayon par défaut est de 0,0. Vous devez la définir dans votre requête sur une valeur supérieure à 0,0.
Par exemple :
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Paramètres facultatifs
-
inclusTypes/excludedTypes, inclusPrimaryTypes/excludedPrimaryTypes
Permet de spécifier une liste de types à partir des types du Tableau A utilisés pour filtrer les résultats de la recherche. Vous pouvez spécifier jusqu'à 50 types dans chaque catégorie de restriction de type.
Un lieu ne peut avoir qu'un seul type principal issu des types du Tableau A. Par exemple, le type principal peut être
"mexican_restaurant"
ou"steak_house"
. UtilisezincludedPrimaryTypes
etexcludedPrimaryTypes
pour filtrer les résultats en fonction du type principal d'un lieu.Un lieu peut également avoir plusieurs valeurs de type issues des types du Tableau A. Par exemple, un restaurant peut présenter les types suivants :
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. UtilisezincludedTypes
etexcludedTypes
pour filtrer les résultats sur la liste des types associés à un lieu.Si une recherche est spécifiée avec plusieurs restrictions de type, seuls les lieux qui répondent à toutes les restrictions sont renvoyés. Par exemple, si vous spécifiez
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, les lieux renvoyés fournissent des services associés à"restaurant"
, mais ne fonctionnent pas principalement en tant que"steak_house"
.includedTypes
Liste des types de lieux à rechercher dans le Tableau A, séparés par une virgule. Si ce paramètre est omis, des lieux de tous types sont renvoyés.
excludedTypes
Liste des types de lieux du Tableau A à exclure d'une recherche, séparés par une virgule.
Si vous spécifiez à la fois le
includedTypes
( par exemple,"school"
) et leexcludedTypes
(tel que"primary_school"
) dans la requête, la réponse inclut les lieux classés dans la catégorie"school"
, mais pas"primary_school"
. La réponse inclut des lieux correspondant à au moins un des élémentsincludedTypes
et aucun des élémentsexcludedTypes
.S'il existe des types en conflit, par exemple un type qui apparaît à la fois dans
includedTypes
etexcludedTypes
, une erreurINVALID_REQUEST
est renvoyée.includedPrimaryTypes
Liste des principaux types de lieux principaux du Tableau A à inclure dans une recherche, séparés par une virgule.
excludedPrimaryTypes
Liste des types de lieux principaux du Tableau A à exclure d'une recherche, séparés par une virgule.
S'il existe des types principaux en conflit, par exemple un type qui apparaît à la fois dans
includedPrimaryTypes
etexcludedPrimaryTypes
, une erreurINVALID_ARGUMENT
est renvoyée. -
languageCode
Langue dans laquelle les résultats doivent être renvoyés.
- Consultez la liste des langues acceptées. Cette liste n'est peut-être pas exhaustive, car Google met régulièrement à jour les langues acceptées.
- Si
languageCode
n'est pas fourni, l'API est définie par défaut suren
. Si vous spécifiez un code de langue non valide, l'API renvoie une erreurINVALID_ARGUMENT
. - L'API s'efforce de fournir une adresse postale lisible à la fois pour l'utilisateur et pour les locaux. Pour atteindre cet objectif, il renvoie les adresses postales dans la langue locale, translittérées en un script que l'utilisateur peut lire si nécessaire, en tenant compte de la langue préférée. Toutes les autres adresses sont affichées dans la langue préférée. Les composants d'adresse sont tous renvoyés dans la même langue, choisie dans le premier composant.
- Si un nom n'est pas disponible dans la langue préférée, l'API utilise le nom correspondant le plus proche.
- La langue préférée a une petite influence sur l'ensemble des résultats que l'API choisit de renvoyer et sur l'ordre dans lequel ils sont renvoyés. Le geocoder interprète les abréviations différemment selon la langue. Il peut s'agir, par exemple, des abréviations correspondant aux types de rues ou des synonymes qui peuvent être valides dans une langue, mais pas dans une autre.
-
maxResultCount
Spécifie le nombre maximal de résultats de lieu à renvoyer. Doit être comprise entre 1 et 20 (par défaut) inclus.
-
rankPreference
Type de classement à utiliser. Si ce paramètre est omis, les résultats sont classés en fonction de leur popularité. Il peut s'agir de l'un des éléments suivants:
POPULARITY
(par défaut) Trie les résultats en fonction de leur popularité.DISTANCE
Trie les résultats par ordre croissant en fonction de leur distance par rapport à l'emplacement spécifié.
-
regionCode
Code régional utilisé pour mettre en forme la réponse, spécifié sous la forme d'une valeur de code CLDR à deux caractères. Il n'existe pas de valeur par défaut.
Si le nom de pays du champ
formattedAddress
dans la réponse correspond àregionCode
, le code pays est omis deformattedAddress
. Ce paramètre n'a aucun effet suradrFormatAddress
, qui inclut toujours le nom du pays, ni surshortFormattedAddress
, qui ne l'inclut jamais.La plupart des codes CLDR sont identiques aux codes ISO 3166-1, à quelques exceptions près. Par exemple, le ccTLD du Royaume-Uni est "uk" (.co.uk), tandis que son code ISO 3166-1 est "gb" (techniquement pour l'entité "Royaume-Uni de Grande-Bretagne et d'Irlande du Nord"). Ce paramètre peut avoir un impact sur les résultats en fonction du droit applicable.
Exemples de recherche à proximité (nouveau)
Rechercher des lieux d'un type donné
L'exemple suivant montre une requête Nearby Search (New) pour les noms à afficher de tous les restaurants dans un rayon de 500 mètres, défini par circle
:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Notez que l'en-tête X-Goog-FieldMask
spécifie que la réponse contient les champs de données suivants: places.displayName
.
La réponse se présente alors sous la forme suivante:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
Ajoutez d'autres types de données au masque de champ pour renvoyer des informations supplémentaires.
Par exemple, ajoutez places.formattedAddress,places.types,places.websiteUri
pour inclure l'adresse, le type et l'adresse Web du restaurant dans la réponse:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
La réponse se présente désormais sous la forme suivante:
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
Rechercher des lieux de différents types
L'exemple suivant montre une requête Nearby Search (New) pour les noms à afficher de tous les magasins de proximité et de spiritueux dans un rayon de 1 000 mètres autour du circle
spécifié:
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearbyCet exemple ajoute
places.primaryType
et places.types
au masque de champ afin que la réponse inclue des informations de type sur chaque lieu, ce qui facilite la sélection du lieu approprié dans les résultats.
Exclure un type de lieu d'une recherche
L'exemple suivant montre une requête Nearby Search (New) pour tous les lieux de type "school"
, en excluant tous les lieux de type "primary_school"
, en classant les résultats par distance:
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Rechercher tous les lieux à proximité d'une zone, classés par distance
L'exemple suivant illustre une requête Nearby Search (New) pour des lieux à proximité d'un point du centre-ville de San Francisco. Dans cet exemple, vous incluez le paramètre rankPreference
pour classer les résultats en fonction de la distance:
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Essayer
APIs Explorer vous permet de créer des exemples de requêtes afin que vous puissiez vous familiariser avec l'API et ses options.
- Sélectionnez l'icône API sur le côté droit de la page.
- Vous pouvez également développer Afficher les paramètres standards et définir le paramètre
fields
sur le masque de champ. - Vous pouvez également modifier le corps de la requête.
- Sélectionnez le bouton Execute (Exécuter). Dans la fenêtre pop-up, sélectionnez le compte à utiliser pour effectuer la demande.
Dans le panneau APIs Explorer, sélectionnez l'icône de développement pour développer la fenêtre de l'explorateur d'API.