Présentation
Les fonctions de la bibliothèque Places, API Maps JavaScript permettent à votre application de rechercher des lieux (définis dans cette API comme des établissements, des emplacements géographiques ou des points d'intérêt importants) dans une zone définie, comme les limites d'une carte ou la surface autour d'un point fixe.
L'API Places propose une fonctionnalité de saisie semi-automatique qui vous permet de donner à vos applications le comportement de recherche anticipée du champ de recherche Google Maps. Lorsqu'un utilisateur commence à saisir une adresse, la fonction de saisie semi-automatique la complète. Pour en savoir plus, consultez la documentation sur la saisie semi-automatique.
Premiers pas
Si vous ne connaissez pas l'API Maps JavaScript ou JavaScript, nous vous recommandons de vous familiariser avec ces éléments, et d'obtenir une clé API avant de commencer.
Activer des API
Avant d'utiliser la bibliothèque Places dans l'API Maps JavaScript, vérifiez que l'API Places est activée dans la console Google Cloud, dans le projet que vous avez configuré pour l'API Maps JavaScript.
Pour afficher la liste des API activées :
- Accédez à la console Google Cloud.
- Cliquez sur le bouton Sélectionner un projet, sélectionnez le projet que vous avez configuré pour l'API Maps JavaScript, puis cliquez sur Ouvrir.
- Dans la liste des API du tableau de bord, recherchez API Places.
- Si l'API Places figure dans la liste, cela signifie qu'elle est déjà activée. Si l'API ne figure pas dans la liste, activez-la :
- En haut de la page, sélectionnez ACTIVER DES API ET DES SERVICES pour afficher l'onglet Bibliothèque. Vous pouvez également sélectionner Bibliothèque dans le menu de gauche.
- Recherchez l'API Places, puis sélectionnez-la dans la liste des résultats.
- Sélectionnez ACTIVER. Une fois le processus terminé, l'API Places apparaît dans la liste des API du tableau de bord.
Charger la bibliothèque
Le service Places est une bibliothèque autonome, distincte du code principal de l'API Maps JavaScript. Pour utiliser la fonctionnalité contenue dans cette bibliothèque, vous devez d'abord la charger à l'aide du paramètre libraries
dans l'URL d'amorçage de l'API Google Maps :
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
Pour en savoir plus, consultez la Présentation des bibliothèques.
Ajouter l'API Places à la liste des restrictions d'API de la clé API
Appliquer des restrictions d'API à vos clés limite l'utilisation de la clé API à un ou plusieurs SDK ou API. Les requêtes vers une API ou un SDK associé à la clé API seront traitées. Les requêtes vers une API ou un SDK non associé à la clé API échoueront. Pour restreindre l'utilisation d'une clé API avec l'API Places Library et Maps JavaScript :- Accédez à la console Google Cloud.
- Cliquez sur la liste déroulante du projet, puis sélectionnez le projet contenant la clé API que vous souhaitez sécuriser.
- Cliquez sur le bouton Menu
, puis sélectionnez Google Maps Platform > Identifiants.
- Sur la page Identifiants, cliquez sur le nom de la clé API que vous souhaitez sécuriser.
- Sur la page Restreindre et renommer la clé API, définissez les restrictions :
- Restrictions relatives aux API
- Sélectionnez Restreindre la clé.
- Cliquez sur Sélectionner des API, puis sélectionnez API Maps JavaScript et API Places.
Si l'une des API n'est pas listée, vous devez l'activer.
- Cliquez sur ENREGISTRER.
Limites d'utilisation et règles
Quotas
La Bibliothèque Places partage un quota d'utilisation avec l'API Places, comme décrit dans sa documentation sur les limites d'utilisation.
Règles
L'utilisation de la bibliothèque Places et de l'API Maps JavaScript doit être conforme aux Règles décrites pour l'API Places.
Recherches de lieux
Avec le service Places, vous pouvez effectuer les types de recherches suivants :
- Find Place from Query : renvoie un lieu en fonction d'une requête textuelle (par exemple, le nom ou l'adresse d'un lieu).
- Find Place from Phone Number : renvoie un lieu à partir d'un numéro de téléphone.
- Nearby Search : renvoie une liste de lieux à proximité en fonction de la position de l'utilisateur.
- Recherche de texte : renvoie une liste de lieux à proximité en fonction d'une chaîne de recherche, par exemple "Pizza".
- Les requêtes Place Details renvoient des informations plus détaillées sur un lieu spécifique, y compris des avis d'utilisateurs.
Les informations renvoyées peuvent inclure des établissements comme des restaurants, des magasins ou des bureaux, ainsi que des résultats "geocode" indiquant des adresses ou des entités administratives, comme des communes ou des villes, et d'autres points d'intérêt.
Requêtes Find Place
Les requêtes Find Place vous permettent de rechercher un lieu à l'aide d'une requête textuelle ou d'un numéro de téléphone. Il existe deux types de requêtes Find Place :
Find Place from Query
Find Place from Query renvoie un lieu à partir d'une entrée textuelle. Il peut s'agir de n'importe quel type de lieu, comme un nom d'entreprise ou une adresse. Pour effectuer une requête Find Place from Query, appelez la méthode PlacesService
de findPlaceFromQuery()
, qui utilise les paramètres suivants :
query
(obligatoire) : chaîne de texte sur laquelle doit porter la recherche, par exemple "restaurant" ou "123 Main Street". Il doit s'agir d'un nom de lieu, d'une adresse ou d'une catégorie d'établissements. Tout autre type d'entrée peut générer des erreurs, et ne renverra peut-être pas de résultats valides. L'API Places renvoie les résultats correspondant à cette chaîne et les classe en fonction de leur pertinence estimée.fields
(obligatoire) : un ou plusieurs champs spécifiant les types de données de lieu à renvoyer.locationBias
(facultatif) : coordonnées définissant la zone à rechercher. Il peut s'agir par exemple :- d'un ensemble de coordonnées de latitude et de longitude spécifiées en tant que LatLngLiteral ou qu'objet LatLng ;
- de limites rectangulaires (deux paires de latitude/longitude ou un objet LatLngBounds) ;
- d'un rayon (en mètres) centré sur une latitude/longitude.
Vous devez également transmettre une méthode de rappel à findPlaceFromQuery()
pour gérer l'objet de résultats et la réponse google.maps.places.PlacesServiceStatus
.
L'exemple suivant illustre un appel à findPlaceFromQuery()
pour rechercher "Musée d'art contemporain Australie", et qui inclut les champs name
et geometry
.
var map; var service; var infowindow; function initMap() { var sydney = new google.maps.LatLng(-33.867, 151.195); infowindow = new google.maps.InfoWindow(); map = new google.maps.Map( document.getElementById('map'), {center: sydney, zoom: 15}); var request = { query: 'Museum of Contemporary Art Australia', fields: ['name', 'geometry'], }; var service = new google.maps.places.PlacesService(map); service.findPlaceFromQuery(request, function(results, status) { if (status === google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } map.setCenter(results[0].geometry.location); } }); }Voir un exemple
Find Place from Phone Number
Find Place from Phone Number renvoie un lieu à partir d'un numéro de téléphone. Pour effectuer une requête Find Place from Phone Number, appelez la méthode PlacesService
de findPlaceFromPhoneNumber()
, qui utilise les paramètres suivants :
phoneNumber
(obligatoire) : un numéro de téléphone au format E.164 ;fields
(obligatoire) : un ou plusieurs champs spécifiant les types de données de lieu à renvoyer.locationBias
(facultatif) : coordonnées définissant la zone à rechercher. Il peut s'agir par exemple :- d'un ensemble de coordonnées de latitude et de longitude spécifiées en tant que LatLngLiteral ou qu'objet LatLng ;
- de limites rectangulaires (quatre points de latitude/longitude ou un objet LatLngBounds) ;
- d'un rayon (en mètres) centré sur une latitude/longitude.
Vous devez également transmettre une méthode de rappel à findPlaceFromPhoneNumber()
pour gérer l'objet de résultats et la réponse google.maps.places.PlacesServiceStatus
.
Champs (méthodes Find Place)
Utilisez le paramètre fields
pour spécifier un tableau de types de données de lieu à renvoyer
(par exemple, fields: ['formatted_address', 'opening_hours', 'geometry']
).
Utilisez un point lorsque vous spécifiez des valeurs composées (par exemple, opening_hours.weekday_text
).
Les champs correspondent aux résultats Place Search et sont divisés en trois catégories de facturation : Basic, Contact et Ambiance. Les champs Basic sont facturés au tarif de base et n'entraînent aucuns frais supplémentaires. Les champs Contact et Ambiance sont facturés à un tarif plus élevé. Pour en savoir plus, consultez la grille tarifaire. Les attributions (html_attributions
) sont toujours renvoyées avec chaque appel, que le champ ait été demandé ou non.
Basic
La catégorie Basic inclut les champs suivants :
business_status
, formatted_address
, geometry
,
icon
,icon_mask_base_uri
, icon_background_color
,
name
, permanently_closed
(obsolète),
photos
, place_id
, plus_code
, types
Contact
La catégorie Contact inclut le champ suivant :opening_hours
(obsolète dans la bibliothèque Places, API Maps JavaScript. Utilisez une requête Places Details pour obtenir les résultats
opening_hours
.)
Ambiance
La catégorie Ambiance comprend les champs suivants :price_level
, rating
, user_ratings_total
Les méthodes findPlaceFromQuery()
et findPlaceFromPhoneNumber()
utilisent chacune le même ensemble de champs et peuvent renvoyer les mêmes champs dans leurs réponses respectives.
Définir un biais de localisation (méthodes Find Place)
Utilisez le paramètre locationBias
pour que l'option Find Place favorise les résultats dans une zone particulière. Vous pouvez définir locationBias
comme suit :
Limiter les résultats à une zone spécifique :
locationBias: {lat: 37.402105, lng: -122.081974}
Définir une zone rectangulaire à rechercher :
locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}
Vous pouvez également utiliser LatLngBounds.
Définir un rayon de recherche (en mètres) centré sur une zone particulière :
locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}
Requêtes Nearby Search
Une requête Nearby Search permet de rechercher des lieux dans une zone définie par mot clé ou par type. Une requête Nearby Search doit toujours inclure un lieu, qui doit être spécifié en utilisant au choix :
- un
LatLngBounds
; - une zone circulaire définie comme la combinaison de la propriété
location
(qui spécifie le centre du cercle en tant qu'objetLatLng
) et un rayon, mesuré en mètres.
Une recherche Places Nearby est initiée par un appel à la méthode nearbySearch()
de
PlacesService
, qui renvoie un tableau d'objets
PlaceResult
. Notez que la méthode nearbySearch()
remplace la méthode search()
à partir de la version 3.9.
service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback);
Cette méthode utilise une requête avec les champs suivants :
- Soit :
bounds
, qui doit être un Objetgoogle.maps.LatLngBounds
définissant le rectangle la zone de recherche. Distance en diagonale maximale acceptée pour les limites est d'environ 100 000 mètres.- un
location
et unradius
. La première utilise un objetgoogle.maps.LatLng
et la seconde un entier simple représentant le rayon du cercle en mètres. La valeur est de 50 000 mètres. Notez que lorsquerankBy
est défini sur DISTANCE, vous devez spécifierlocation
. Toutefois, vous ne pouvez définir niradius
, nibounds
.
keyword
(facultatif) : terme à mettre en correspondance avec tous les champs disponibles, y compris, mais sans s'y limiter, le nom, le type et l'adresse, ainsi que les avis des clients et d'autres contenus tiers.minPriceLevel
etmaxPriceLevel
(facultatif) : restreint les résultats aux seuls lieux compris dans la plage spécifiée. Les valeurs valides sont comprises entre 0 (le moins cher) et 4 (le plus cher), inclus.name
(obsolète) : Équivaut àkeyword
. Les valeurs de ce champ sont combinées à celles du champkeyword
et transmises dans la même chaîne de recherche.openNow
(facultatif) : valeur booléenne indiquant que le service Places ne doit renvoyer que les lieux ouverts au moment de l'envoi de la requête. Si vous incluez ce paramètre dans la requête, les lieux qui ne précisent pas d'horaires d'ouverture dans la base de données Google Places ne sont pas renvoyés. DéfiniropenNow
surfalse
n'a aucun effet.rankBy
(facultatif) : spécifie l'ordre dans lequel les résultats sont listés. Les valeurs possibles sont les suivantes :google.maps.places.RankBy.PROMINENCE
(par défaut) : cette option permet de trier les résultats en fonction de leur importance. Ce classement privilégie les lieux importants situés dans le rayon défini par rapport aux lieux situés à proximité qui correspondent au critère de recherche, mais qui sont moins importants. L'importance peut être déterminée par la position du lieu dans l'index Google, sa popularité globale et d'autres facteurs. Lorsquegoogle.maps.places.RankBy.PROMINENCE
est spécifié, le paramètreradius
est obligatoire.google.maps.places.RankBy.DISTANCE
: cette option trie les résultats par ordre croissant selon leur distance par rapport à l'élémentlocation
spécifié (obligatoire). Notez que vous ne pouvez pas spécifier debounds
personnalisé ni deradius
si vous spécifiezRankBy.DISTANCE
. Lorsque vous spécifiezRankBy.DISTANCE
, au moins un des élémentskeyword
,name
outype
est requis.
type
: limite les résultats aux lieux correspondant au type spécifié. Un seul type peut être spécifié (si plusieurs types sont fournis, tous les types spécifiés après la première entrée sont ignorés). Consultez la liste des types compatibles.
Vous devez également transmettre une méthode de rappel à nearbySearch()
pour gérer l'objet de résultats et la réponse google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', type: ['restaurant'] }; service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } } }
Requêtes Text Search
Le service Text Search de Google Places est un service Web qui renvoie des informations sur un ensemble de lieux en fonction d'une chaîne de texte (par exemple, "pizza à New York" ou "magasins de chaussures près d'Ottawa"). Ce service renvoie une liste des lieux correspondant à la chaîne de texte et aux limitations de zone géographique définis. La réponse à la recherche inclut une liste de lieux. Vous pouvez ajouter une requête Places Details pour obtenir plus d'informations sur les lieux indiqués dans la réponse.
Les recherches Text Search sont lancées avec un appel à la méthode textSearch()
de PlacesService
.
service = new google.maps.places.PlacesService(map); service.textSearch(request, callback);
Cette méthode utilise une requête avec les champs suivants :
query
(obligatoire) : chaîne de texte sur laquelle doit porter la recherche, par exemple "restaurant" ou "123 Main Street". Il doit s'agir d'un nom de lieu, d'une adresse ou d'une catégorie d'établissements. Tout autre type d'entrée peut générer des erreurs, et peuvent ne pas renvoyer de résultats valides. Le service Places renvoie les résultats correspondant à cette chaîne et les classe en fonction de leur pertinence estimée. Ce paramètre devient facultatif sitype
est également utilisé dans la requête de recherche.- Facultatif :
openNow
: valeur booléenne indiquant que le service Places ne doit renvoyer que les lieux ouverts au moment de l'envoi de la requête. Si vous incluez ce paramètre dans la requête, les lieux sans horaires d'ouverture dans la base de données Google Places ne sont pas renvoyés. DéfiniropenNow
surfalse
n'a aucun effet.minPriceLevel
etmaxPriceLevel
: restreint les résultats aux seuls lieux compris dans la fourchette de prix spécifiée. Les valeurs valides sont comprises entre 0 (le moins cher) et 4 (le plus cher), inclus.- Soit :
bounds
, qui doit être un Objetgoogle.maps.LatLngBounds
définissant le rectangle la zone de recherche. Distance en diagonale maximale acceptée pour les limites est d'environ 100 000 mètres.location
etradius
: vous pouvez affiner les résultats à un cercle donné en transmettant les paramètreslocation
etradius
. Vous indiquez ainsi au service Places de privilégier les résultats situés à l'intérieur de ce cercle. Des résultats en dehors de la zone définie peuvent toutefois être affichés. L'emplacement utilise un objetgoogle.maps.LatLng
, et le rayon est un entier simple représentant le rayon du cercle en mètres. Le rayon maximum autorisé est de 50 000 mètres.
type
: limite les résultats aux lieux correspondant au type spécifié. Un seul type peut être spécifié (si plusieurs types sont fournis, tous les types spécifiés après la première entrée sont ignorés). Consultez la liste des types compatibles.
Vous devez également transmettre une méthode de rappel à textSearch()
pour gérer l'objet de résultats et la réponse google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', query: 'restaurant' }; service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { var place = results[i]; createMarker(results[i]); } } }
Réponses aux recherches
Codes d'état
L'objet de réponse PlacesServiceStatus
contient l'état de la requête et éventuellement des informations de débogage qui vous aident à savoir pourquoi la requête de lieu a échoué. Les valeurs possibles sont les suivantes :
INVALID_REQUEST
: la requête n'est pas valide.OK
: la réponse contient un résultat valide.OVER_QUERY_LIMIT
: la page Web a dépassé son quota de requêtes.REQUEST_DENIED
: la page Web n'est pas autorisée à utiliser PlacesService.UNKNOWN_ERROR
: la requête PlacesService n'a pas pu être traitée en raison d'une erreur de serveur. Si vous essayez à nouveau, la requête pourrait aboutir.ZERO_RESULTS
: aucun résultat n'a été trouvé pour cette requête.
Résultats Place Search
Les fonctions findPlace()
, nearbySearch()
et textSearch()
renvoient un tableau d'objets PlaceResult
.
Chaque objet PlaceResult
peut inclure les propriétés suivantes :
business_status
indique l'état opérationnel du lieu (s'il s'agit d'une entreprise). Il peut contenir l'une des valeurs suivantes :OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
n'est pas renvoyé.formatted_address
est une chaîne contenant l'adresse lisible de ce lieu. La propriétéformatted_address
n'est renvoyée que pour une recherche Text Search.Bien souvent, cette adresse équivaut à l'adresse postale. Notez que certains pays, comme le Royaume-Uni, n'autorisent pas la distribution des vraies adresses postales en raison de restrictions de licence.
L'adresse formatée est composée d'un ou de plusieurs composants d'adresse logiques. Par exemple, l'adresse "111 8th Avenue, New York, NY" comprend les éléments suivants : "111" (le numéro de rue), "8th Avenue" (la route), "New York" (la ville) et "NY" (l'État américain).
N'analysez pas l'adresse formatée de manière programmatique. Utilisez plutôt les composants d'adresse individuels, que la réponse de l'API inclut en plus du champ d'adresse formaté.
geometry
: fournit les informations liées aux propriétés géométriques du lieu. Par exemple :location
fournit la latitude et la longitude du lieu.viewport
définit la fenêtre d'affichage préférée sur la carte lorsque ce lieu est affiché.
permanently_closed
(obsolète) est un indicateur booléen qui précise si le lieu a fermé définitivement ou temporairement (valeurtrue
). N'utilisez paspermanently_closed
. Utilisez plutôtbusiness_status
pour obtenir l'état opérationnel des entreprises.plus_code
: (voir Open Location Code et Plus Codes) référence de lieu encodée, calculée à partir de coordonnées de latitude et de longitude, qui représente une zone : 1/8000e de degré par 1/8000e de degré (environ 14 m x 14 m à l'équateur) ou moins. Vous pouvez utiliser des Plus Codes pour remplacer les adresses postales dans les endroits où elles n'existent pas (où les bâtiments ne sont pas numérotés ni nommés).Les Plus Codes sont mis en forme comme un code global et un code composé :
global_code
est un indicatif de zone à 4 caractères et un indicatif local à 6 caractères ou plus (849VCWC8+R9).compound_code
est un code local à six caractères ou plus avec un emplacement explicite (CWC8+R9, Mountain View, CA, États-Unis). N'analysez pas ce contenu de manière programmatique.
html_attributions
: tableau des mentions que vous devez afficher dans les résultats de recherche. Chaque entrée du tableau contient le texte HTML d'une mention unique. Remarque : il s'agit d'une agrégation de toutes les mentions pour la réponse à la recherche dans son ensemble. Tous les objetsPlaceResult
de la réponse contiennent donc des listes d'attribution identiques.icon
renvoie l'URL associée à une icône colorée de 71 x 71 pixels au format PNG.icon_mask_base_uri
renvoie l'URL de base d'une icône non colorée, sans l'extension .svg ou .png.icon_background_color
renvoie le code couleur hexadécimale par défaut pour la catégorie du lieu.name
: nom du lieu.opening_hours
peut contenir les informations suivantes :open_now
est une valeur booléenne indiquant si le lieu est ouvert à l'heure actuelle (obsolète dans la bibliothèque Places, API Maps JavaScript, utilisez plutôtutc_offset_minutes
).
place_id
est un identifiant textuel qui identifie un lieu de manière unique. Pour récupérer des informations sur le lieu, transmettez cet identifiant dans la requête Place Details. Découvrez comment référencer un lieu avec un ID de lieu.rating
contient la note du lieu, sur une échelle de 0,0 à 5,0, basée sur l'ensemble des avis des utilisateurs.types
: tableau des types pour ce lieu (par exemple,["political", "locality"]
ou["restaurant", "lodging"]
). Ce tableau peut contenir plusieurs valeurs ou être vide. De nouvelles valeurs peuvent être ajoutées sans préavis. Consultez la liste des types compatibles.vicinity
: adresse simplifiée du lieu, comprenant la rue, le numéro et la ville, mais sans le département/la province, le code postal ou le pays. Par exemple, la valeur devicinity
du bureau de Google à Sydney en Australie est de5/48 Pirrama Road, Pyrmont
.
Accéder à des résultats supplémentaires
Par défaut, chaque recherche de lieu renvoie jusqu'à 20 résultats par requête. Toutefois, chaque recherche peut renvoyer jusqu'à 60 résultats, répartis sur trois pages.
Des pages supplémentaires sont disponibles via l'objet PlaceSearchPagination
. Pour accéder à ces pages supplémentaires, vous devez capturer l'objet PlaceSearchPagination
avec une fonction de rappel. L'objet PlaceSearchPagination
est défini comme suit :
hasNextPage
: une propriété booléenne qui indique si d'autres résultats sont disponibles. Elle esttrue
lorsqu'il existe une page de résultats supplémentaire.nextPage()
: une fonction qui renvoie l'ensemble de résultats suivant. Après avoir exécuté une recherche, vous devez attendre deux secondes avant que la page de résultats suivante soit disponible.
Pour afficher les résultats suivants, appelez nextPage
.
Chaque page de résultats doit être affichée avant de pouvoir afficher la suivante. Notez que chaque résultat correspond à une requête unique dans vos limites d'utilisation.
L'exemple ci-dessous montre comment modifier votre fonction de rappel pour capturer l'objet PlaceSearchPagination
pour envoyer plusieurs requêtes de recherche.
TypeScript
// This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initMap(): void { // Create the map. const pyrmont = { lat: -33.866, lng: 151.196 }; const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { center: pyrmont, zoom: 17, mapId: "8d193001f940fde3", } as google.maps.MapOptions ); // Create the places service. const service = new google.maps.places.PlacesService(map); let getNextPage: () => void | false; const moreButton = document.getElementById("more") as HTMLButtonElement; moreButton.onclick = function () { moreButton.disabled = true; if (getNextPage) { getNextPage(); } }; // Perform a nearby search. service.nearbySearch( { location: pyrmont, radius: 500, type: "store" }, ( results: google.maps.places.PlaceResult[] | null, status: google.maps.places.PlacesServiceStatus, pagination: google.maps.places.PlaceSearchPagination | null ) => { if (status !== "OK" || !results) return; addPlaces(results, map); moreButton.disabled = !pagination || !pagination.hasNextPage; if (pagination && pagination.hasNextPage) { getNextPage = () => { // Note: nextPage will call the same handler function as the initial call pagination.nextPage(); }; } } ); } function addPlaces( places: google.maps.places.PlaceResult[], map: google.maps.Map ) { const placesList = document.getElementById("places") as HTMLElement; for (const place of places) { if (place.geometry && place.geometry.location) { const image = { url: place.icon!, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; new google.maps.Marker({ map, icon: image, title: place.name!, position: place.geometry.location, }); const li = document.createElement("li"); li.textContent = place.name!; placesList.appendChild(li); li.addEventListener("click", () => { map.setCenter(place.geometry!.location!); }); } } } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initMap() { // Create the map. const pyrmont = { lat: -33.866, lng: 151.196 }; const map = new google.maps.Map(document.getElementById("map"), { center: pyrmont, zoom: 17, mapId: "8d193001f940fde3", }); // Create the places service. const service = new google.maps.places.PlacesService(map); let getNextPage; const moreButton = document.getElementById("more"); moreButton.onclick = function () { moreButton.disabled = true; if (getNextPage) { getNextPage(); } }; // Perform a nearby search. service.nearbySearch( { location: pyrmont, radius: 500, type: "store" }, (results, status, pagination) => { if (status !== "OK" || !results) return; addPlaces(results, map); moreButton.disabled = !pagination || !pagination.hasNextPage; if (pagination && pagination.hasNextPage) { getNextPage = () => { // Note: nextPage will call the same handler function as the initial call pagination.nextPage(); }; } }, ); } function addPlaces(places, map) { const placesList = document.getElementById("places"); for (const place of places) { if (place.geometry && place.geometry.location) { const image = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; new google.maps.Marker({ map, icon: image, title: place.name, position: place.geometry.location, }); const li = document.createElement("li"); li.textContent = place.name; placesList.appendChild(li); li.addEventListener("click", () => { map.setCenter(place.geometry.location); }); } } } window.initMap = initMap;
Essayer l'exemple
Place Details
En plus de fournir une liste de lieux dans une zone donnée, le service Places peut également renvoyer des informations détaillées sur un lieu en particulier. Lorsqu'un lieu est renvoyé dans une réponse à une recherche de lieu, son ID de lieu peut être utilisé pour demander des informations supplémentaires, comme son adresse complète, son numéro de téléphone, les avis et notes des visiteurs, etc.
Requêtes Place Details
Les requêtes Place Details sont effectuées via un appel à la méthode getDetails()
du service.
service = new google.maps.places.PlacesService(map); service.getDetails(request, callback);
Cette méthode utilise une requête qui contient le placeId
du lieu souhaité et des champs indiquant les types de données Places à renvoyer. Découvrez comment référencer un lieu avec un ID de lieu.
Vous devrez également utiliser une méthode de rappel, qui doit gérer le code d'état transmis dans la réponse google.maps.places.PlacesServiceStatus
, ainsi que l'objet google.maps.places.PlaceResult
.
var request = { placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4', fields: ['name', 'rating', 'formatted_phone_number', 'geometry'] }; service = new google.maps.places.PlacesService(map); service.getDetails(request, callback); function callback(place, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { createMarker(place); } }
Champs (Place Details)
Le paramètrefields
accepte un tableau de chaînes (noms de champs).
Utilisez le paramètre fields
pour spécifier un tableau de types de données de lieu à renvoyer
(par exemple, fields: ['address_components', 'opening_hours', 'geometry']
).
Utilisez un point lorsque vous spécifiez des valeurs composées (par exemple, opening_hours.weekday_text
).
Les champs correspondent aux résultats Place Details et sont divisés en trois catégories de facturation : Basic, Contact et Ambiance. Les champs Basic sont facturés au tarif de base et n'entraînent aucuns frais supplémentaires. Les champs Contact et Ambiance sont facturés à un tarif plus élevé. Pour en savoir plus, consultez la grille tarifaire. Les attributions (html_attributions
) sont toujours renvoyées avec chaque appel, qu'elles aient été demandées ou non.
Basic
La catégorie "Basic" comprend les champs suivants :
address_components
, adr_address
, business_status
,
formatted_address
, geometry
, icon
,
icon_mask_base_uri
, icon_background_color
,name
,
permanently_closed
(obsolète),
photo
, place_id
, plus_code
, type
,
url
, utc_offset
(obsolète dans la bibliothèque Places, l'API Maps JavaScript), utc_offset_minutes
,
vicinity
Contact
La catégorie "Contact" comprend les champs suivants :
formatted_phone_number
, international_phone_number
,
opening_hours
et website
Ambiance
La catégorie "Ambiance" comprend les champs suivants :
price_level
, rating
, reviews
,
user_ratings_total
En savoir plus sur les champs de lieu. Pour en savoir plus sur la facturation des requêtes de données de lieu, consultez Utilisation et facturation.
Réponses Place Details
Codes d'état
L'objet de réponse PlacesServiceStatus
contient l'état de la requête et éventuellement des informations de débogage qui vous aident à savoir pourquoi la requête Place Details a échoué. Les valeurs possibles sont les suivantes :
INVALID_REQUEST
: la requête n'est pas valide.OK
: la réponse contient un résultat valide.OVER_QUERY_LIMIT
: la page Web a dépassé son quota de requêtes.NOT_FOUND
: L'emplacement référencé est introuvable dans la base de données Places.REQUEST_DENIED
: la page Web n'est pas autorisée à utiliser PlacesService.UNKNOWN_ERROR
: la requête PlacesService n'a pas pu être traitée en raison d'une erreur de serveur. Si vous essayez à nouveau, la requête pourrait aboutir.ZERO_RESULTS
: aucun résultat n'a été trouvé pour cette requête.
Résultats des requêtes Place Details
Un appel getDetails()
qui aboutit renvoie un objet PlaceResult
avec les propriétés suivantes :
address_components
: tableau contenant les composants distincts applicables à cette adresse.Chaque composant d'adresse contient généralement les champs suivants :
types[]
est un tableau indiquant le type du composant d'adresse. Consultez la liste des types compatibles.long_name
est la description complète ou le nom du composant d'adresse renvoyé par le geocoder.short_name
est un nom textuel abrégé pour le composant d'adresse, s'il est disponible. Par exemple, un composant d'adresse pour l'Alaska peut avoir "Alaska" commelong_name
et "AK" commeshort_name
, correspondant à l'abréviation postale de deux lettres.
Notez les informations suivantes concernant le tableau
address_components[]
:- Le tableau de composants d'adresse peut contenir
formatted_address
et des composants supplémentaires. - Le tableau n'inclut pas nécessairement toutes les entités politiques contenant une adresse, à l'exception de celles incluses dans
formatted_address
. Pour récupérer toutes les entités politiques contenant une adresse spécifique, vous devez utiliser le geocoding inversé, en transmettant à la requête la latitude/longitude de l'adresse en tant que paramètre. - Le format de la réponse ne sera peut-être pas le même d'une requête à l'autre. En particulier, le nombre d'
address_components
varie selon l'adresse demandée et peut changer au fil du temps pour la même adresse. Un composant peut changer de position dans le tableau. Le type du composant peut changer. Un composant particulier peut être manquant dans une réponse ultérieure.
business_status
indique l'état opérationnel du lieu (s'il s'agit d'une entreprise). Il peut contenir l'une des valeurs suivantes :OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
n'est pas renvoyé.formatted_address
: adresse lisible de ce lieu.Bien souvent, cette adresse équivaut à l'adresse postale. Notez que certains pays, comme le Royaume-Uni, n'autorisent pas la distribution des vraies adresses postales en raison de restrictions de licence.
L'adresse formatée est composée d'un ou de plusieurs composants d'adresse logiques. Par exemple, l'adresse "111 8th Avenue, New York, NY" comprend les éléments suivants : "111" (le numéro de rue), "8th Avenue" (la route), "New York" (la ville) et "NY" (l'État américain).
N'analysez pas l'adresse formatée de manière programmatique. Utilisez plutôt les composants d'adresse individuels, que la réponse de l'API inclut en plus du champ d'adresse formaté.
formatted_phone_number
: numéro de téléphone du lieu, au format conforme à la norme régionale.geometry
: fournit les informations liées aux propriétés géométriques du lieu. Par exemple :location
fournit la latitude et la longitude du lieu.viewport
définit la fenêtre d'affichage préférée sur la carte lorsque ce lieu est affiché.
permanently_closed
(obsolète) est un indicateur booléen qui précise si le lieu a fermé définitivement ou temporairement (valeurtrue
). N'utilisez paspermanently_closed
. Utilisez plutôtbusiness_status
pour obtenir l'état opérationnel des entreprises.plus_code
: (voir Open Location Code et Plus Codes) référence de lieu encodée, calculée à partir de coordonnées de latitude et de longitude, qui représente une zone : 1/8000e de degré par 1/8000e de degré (environ 14 m x 14 m à l'équateur) ou moins. Vous pouvez utiliser des Plus Codes pour remplacer les adresses postales dans les endroits où elles n'existent pas (où les bâtiments ne sont pas numérotés ni nommés).Les Plus Codes sont mis en forme comme un code global et un code composé :
global_code
est un indicatif de zone à 4 caractères et un indicatif local à 6 caractères ou plus (849VCWC8+R9).compound_code
est un code local à six caractères ou plus avec un emplacement explicite (CWC8+R9, Mountain View, CA, États-Unis). N'analysez pas ce contenu de manière programmatique.
html_attributions
: texte de la mention à afficher pour ce résultat de lieu.icon
: URL d'une ressource d'image pouvant être utilisée pour représenter le type de ce lieu.international_phone_number
contient le numéro de téléphone du lieu au format international. Le format international inclut l'indicatif du pays, précédé du signe plus (+). Par exemple, leinternational_phone_number
pour le bureau de Google à Sydney, en Australie, est+61 2 9374 4000
.name
: nom du lieu.utc_offset
: obsolète dans la Bibliothèque Places, API Maps JavaScript, utilisezutc_offset_minutes
à la place.utc_offset_minutes
indique le décalage horaire actuel du lieu par rapport à UTC, exprimé en minutes. Par exemple, pour les lieux situés à Sydney, Australie, en heure d'été, ce paramètre est 660 (+11 heures par rapport à l'heure UTC). Pour les lieux situés en Californie, en heure d'hiver, ce paramètre est -480 (-8 heures par rapport à l'heure UTC).opening_hours
contient les informations suivantes :open_now
(obsolète dans la bibliothèque Places, API Maps JavaScript. Utilisez plutôt opening_hours.isOpen(). Regardez cette vidéo pour découvrir comment utiliserisOpen
avec Place Details.) est une valeur booléenne indiquant si l'établissement est ouvert à l'heure actuelle.periods[]
est un tableau de périodes d'ouverture sur sept jours à partir du dimanche, dans l'ordre chronologique. Chaque période contient les éléments suivants :open
contient une paire d'objets de jour et d'heure décrivant les horaires d'ouverture du lieu :day
est un nombre compris entre 0 et 6, correspondant aux jours de la semaine (0 correspondant à dimanche). Par exemple, le 2 correspond au mardi.time
peut contenir une heure de la journée au format 24 heures hhmm (les valeurs sont comprises entre 0000 et 2359).time
sera indiqué dans le fuseau horaire du lieu.
close
peut contenir une paire d'objets de jour et d'heure décrivant les horaires de fermeture de l'établissement. Remarque : Si un lieu est toujours ouvert, la sectionclose
ne figurera pas dans la réponse. Vous pouvez représenter un lieu toujours ouvert par une périodeopen
contenantday
avec la valeur 0 ettime
avec la valeur 0000, et aucunclose
.
weekday_text
est un tableau de sept chaînes représentant les horaires d'ouverture formatées pour chaque jour de la semaine. Si un paramètrelanguage
a été spécifié dans la requête Places Details, le service Places formate et localise les horaires d'ouverture de manière appropriée pour cette langue. L'ordre des éléments dans le tableau dépend du paramètrelanguage
. Pour certaines langues, le premier jour de la semaine est le lundi. Pour d'autres, c'est le dimanche.
permanently_closed
(obsolète) est un indicateur booléen qui précise si le lieu a fermé définitivement ou temporairement (valeurtrue
). N'utilisez paspermanently_closed
. Utilisez plutôtbusiness_status
pour obtenir l'état opérationnel des entreprises.photos[]
: tableau d'objetsPlacePhoto
UnPlacePhoto
peut être utilisé pour obtenir une photo avec la méthodegetUrl()
. Vous pouvez également inspecter l'objet à la recherche des valeurs suivantes :height
: hauteur maximale de l'image, en pixels.width
: largeur maximale de l'image, en pixels.html_attributions
: texte de la mention à afficher pour cette photo de lieu.
place_id
: identifiant textuel qui identifie un lieu de manière unique, et qui peut être utilisé pour récupérer des informations sur ce lieu via une requête Places Details. Découvrez comment référencer un lieu avec un ID de lieu.rating
: note du lieu, sur une échelle de 0,0 à 5,0, basée sur l'ensemble des avis des utilisateurs.reviews
: tableau comportant jusqu'à cinq avis. Chaque avis contient plusieurs composants :aspects[]
contient un tableau d'objetsPlaceAspectRating
, chacun fournissant une note concernant un seul attribut de l'établissement. Le premier objet du tableau est considéré comme l'aspect principal. ChaquePlaceAspectRating
est défini comme suit :type
: le nom de l'aspect évalué. Les types suivants sont acceptés :appeal
,atmosphere
,decor
,facilities
,food
,overall
,quality
etservice
.rating
est la note de l'utilisateur pour l'aspect évalué, sur une échelle de 0 à 3.
author_name
est le nom de l'utilisateur qui a envoyé l'avis. Les avis anonymes sont attribués à "Un utilisateur Google". Si un paramètre de langue a été défini, l'expression "Un utilisateur Google" renvoie une chaîne localisée.author_url
: URL du profil Google+ de l'utilisateur, si disponible.language
: code de langue IETF indiquant la langue utilisée dans l'avis de l'utilisateur. Ce champ contient uniquement l'indicateur principal de la langue et non le tag secondaire qui précise le pays ou la région. Par exemple, toutes les évaluations en anglais sont signalées par "en", et non "en-AU", "en-UK", etc.rating
: la note globale que l'utilisateur a attribuée à ce lieu. Il s'agit d'un nombre entier compris entre 1 et 5.text
: avis de l'utilisateur. Lorsqu'un utilisateur rédige un avis sur un lieu avec Google Places, les évaluations texte sont considérées comme facultatives. Ce champ peut donc être vide.
types
: tableau des types pour ce lieu (par exemple,["political", "locality"]
ou["restaurant", "lodging"]
). Ce tableau peut contenir plusieurs valeurs ou être vide. De nouvelles valeurs peuvent être ajoutées sans préavis. Consultez la liste des types compatibles.url
: URL de la page Google officielle de ce lieu. Il s'agit de la page Google contenant les informations les plus pertinentes disponibles sur le lieu. Les applications doivent associer ou intégrer cette page à tout écran qui affiche des résultats détaillés sur le lieu à l'utilisateur.vicinity
: adresse simplifiée du lieu, comprenant la rue, le numéro et la ville, mais sans le département/la province, le code postal ou le pays. Par exemple, la valeur devicinity
du bureau de Google à Sydney en Australie est de5/48 Pirrama Road, Pyrmont
. La propriétévicinity
n'est renvoyée que pour une recherche Nearby Search.website
indique le site Web faisant autorité pour ce lieu, comme la page d'accueil d'un établissement.
Remarque : Il est possible que les notes multidimensionnelles ne soient pas disponibles pour tous les lieux. S'il n'y a pas assez d'évaluations, la réponse contenant les détails inclut une note héritée sur une échelle de 0,0 à 5,0 (si disponible) ou aucune note.
Utiliser le composant Place Overview
Remarque : Cet exemple utilise une bibliothèque Open Source. Pour toute assistance et tout commentaire concernant la bibliothèque, consultez le fichier README.
Testez les composants Web. Utilisez le le composant Web Place Overview pour obtenir des informations sur les lieux sous forme de représentation visuelle.
<ph type="x-smartling-placeholder">![Image montrant des variantes de taille X, S, M, L et XL
Composant Place Overview affiché en fonction du champ de taille saisi par l'utilisateur.](https://developers.google.cn/static/maps/documentation/javascript/images/place-overview-sizes.png?authuser=6&hl=fr)
Référencer un lieu avec un identifiant de lieu
Un ID de lieu est une référence unique à un lieu sur une carte Google. Des identifiants de lieu sont disponibles pour la plupart des points géographiques, y compris les entreprises, points de repère, parcs et intersections.
Pour utiliser un identifiant de lieu dans votre application, vous devez d'abord le rechercher. Il est disponible dans le PlaceResult
d'une requête Place Search ou Details.
Vous pouvez ensuite utiliser cet identifiant de lieu pour rechercher Place Details.
Les ID de lieu ne sont pas soumis aux restrictions de mise en cache stipulées dans la section 3.2.3(b) des conditions d'utilisation de Google Maps Platform. Vous pouvez donc stocker des ID de lieu pour les utiliser ultérieurement. Pour connaître les bonnes pratiques de stockage d'ID de lieu, consultez la présentation des ID de lieu.
var map; function initialize() { // Create a map centered in Pyrmont, Sydney (Australia). map = new google.maps.Map(document.getElementById('map'), { center: {lat: -33.8666, lng: 151.1958}, zoom: 15 }); // Search for Google's office in Australia. var request = { location: map.getCenter(), radius: '500', query: 'Google Sydney' }; var service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } // Checks that the PlacesServiceStatus is OK, and adds a marker // using the place ID and location from the PlacesService. function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { var marker = new google.maps.Marker({ map: map, place: { placeId: results[0].place_id, location: results[0].geometry.location } }); } } google.maps.event.addDomListener(window, 'load', initialize);
Photos du lieu
La fonctionnalité Place Photo vous permet d'ajouter du contenu photographique de qualité supérieure à votre site. Le service Photo vous donne accès à des millions de photos stockées dans les bases de données Places et Google + Local. Lorsque vous obtenez des informations sur un lieu à l'aide d'une requête de Places Details, des références photo sont renvoyées pour le contenu photographique correspondant. Les requêtes Nearby Search et Text Search renvoient également une référence photo unique par lieu, le cas échéant. Le service Photo vous permet ensuite d'accéder aux photos référencées et de redimensionner l'image pour qu'elle s'adapte parfaitement à votre application.
Un tableau d'objets PlacePhoto
sera renvoyé dans l'objet PlaceResult
pour toute requête getDetails()
, textSearch()
ou nearbySearch()
effectuée concernant PlacesService
.
Remarque : Le nombre de photos renvoyées varie en fonction de la requête.
- Une recherche Nearby Search ou Text Search renvoie au maximum un objet
PlacePhoto
. - Une requête Details renvoie jusqu'à 10 objets
PlacePhoto
.
Vous pouvez demander l'URL de l'image associée en appelant la méthode PlacePhoto.getUrl()
et en transmettant un objet PhotoOptions
valide. L'objet PhotoOptions
vous permet de spécifier la hauteur et la largeur maximales souhaitées pour l'image. Si vous spécifiez une valeur pour maxHeight
et maxWidth
, le service de photo redimensionne l'image à la plus petite des deux tailles, tout en conservant le format d'origine.
L'extrait de code suivant accepte un objet de lieu et ajoute un repère sur la carte si une photo est disponible. L'image du repère par défaut est remplacée par une version réduite de la photo.
function createPhotoMarker(place) { var photos = place.photos; if (!photos) { return; } var marker = new google.maps.Marker({ map: map, position: place.geometry.location, title: place.name, icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35}) }); }
Les photos renvoyées par le service Photo sont extraites de plusieurs sources : elles peuvent être fournies par des propriétaires d'établissement ou par des utilisateurs. Dans la plupart des cas, les photos de lieu peuvent être utilisées sans attribution, ou contiendront déjà l'attribution. Toutefois, si l'élément photo
renvoyé inclut une valeur dans le champ html_attributions
, vous devez inclure l'attribution supplémentaire dans votre application partout où vous affichez l'image.