De nouveaux styles de cartes seront bientôt disponibles dans Google Maps Platform. Cette modification des styles de cartes inclut une nouvelle palette de couleurs par défaut, et améliore l'expérience utilisateur et l'usabilité des cartes. Tous les styles de cartes seront automatiquement mis à jour en mars 2025. Pour en savoir plus sur la disponibilité et la façon de s'inscrire plus tôt, consultez Nouveau style de carte pour Google Maps Platform.
Cette page décrit la bibliothèque côté client disponible avec l'API Maps JavaScript. Si vous souhaitez utiliser le service Web de l'API Places sur votre serveur, consultez Client Node.js pour les services Google Maps. La page accessible via ce lien présente également le client Java, le client Python et le client Go pour les services Google Maps.
Introduction
La saisie semi-automatique est une fonctionnalité de la bibliothèque Places de l'API Maps JavaScript. Vous pouvez utiliser la saisie semi-automatique pour reproduire dans votre application le comportement de frappe anticipée qu'utilise le champ de recherche de Google Maps.
Le service de saisie semi-automatique peut établir une correspondance avec des mots complets et des sous-chaînes afin de trouver des noms de lieux, des adresses et des Plus Codes. Ainsi, les applications peuvent envoyer des requêtes lors de la frappe pour indiquer les lieux possibles à la volée. Comme défini par l'API Places, un "lieu" peut être un établissement, un emplacement géographique ou un point d'intérêt.
Comment en profiter ?
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.
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 vous trouvez l'API dans la liste, vous pouvez continuer. Si l'API ne figure pas dans la liste, activez-la :
En haut de la page, sélectionnez ACTIVER L'API 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 :
L'API propose deux types de widgets de saisie semi-automatique, que vous pouvez ajouter via les classes Autocomplete et SearchBox respectivement.
De plus, vous pouvez utiliser la classe AutocompleteService pour récupérer de manière programmatique les résultats de la saisie semi-automatique. Consultez Classe AutocompleteService dans la documentation de référence de l'API Maps JavaScript.
Voici un résumé des classes disponibles :
Autocomplete ajoute un champ de saisie de texte à votre page Web et surveille ce champ pour détecter si des caractères y sont saisis. À mesure que l'utilisateur saisit du texte, la saisie semi-automatique affiche des prédictions de lieu sous la forme d'une liste de sélection déroulante. Lorsque l'utilisateur sélectionne un lieu dans la liste, les informations sur le lieu sont renvoyées à l'objet de saisie semi-automatique et peuvent être récupérées par votre application. Consultez les détails ci-dessous.
Figure 1 : Champ de texte avec saisie semi-automatique et liste de sélectionFigure 2 : Formulaire d'adresse rempli
SearchBox ajoute un champ de saisie de texte à votre page Web, quasiment de la même manière qu'Autocomplete. Les différences sont les suivantes :
La principale différence réside dans les résultats qui s'affichent dans la liste de sélection. SearchBox fournit une liste étendue de prédictions, qui peut inclure des lieux (tels que définis par l'API Places) ainsi que des suggestions de termes de recherche. Par exemple, si l'utilisateur saisit "pizza à new", la liste de sélection peut proposer "pizza à New York, NY", ainsi que le nom de plusieurs pizzerias.
SearchBox propose moins d'options que Autocomplete pour limiter la recherche. Dans le premier cas, vous pouvez orienter la recherche vers un LatLngBounds donné. Dans le second cas, non seulement vous pouvez restreindre la recherche à un pays et à des types de lieux en particulier, mais vous pouvez également définir des limites. Pour en savoir plus, consultez la rubrique ci-dessous.
Figure 3 : Un champ de recherche présentant des termes de recherche et des prédictions de lieux.Consultez les détails ci-dessous.
Vous pouvez créer un objet AutocompleteService pour récupérer des prédictions de manière programmatique. Appelez getPlacePredictions() pour obtenir des lieux correspondants, ou getQueryPredictions() pour récupérer les lieux et des suggestions de termes de recherche.
Remarque : AutocompleteService n'ajoute aucune commande d'interface utilisateur.
À la place, les méthodes ci-dessus renvoient un tableau d'objets de prédiction. Chaque objet de prédiction contient le texte de la prédiction ainsi que des informations de référence et des détails sur la manière dont les résultats correspondent à ce qu'a saisi l'utilisateur. Consultez les détails ci-dessous.
Ajouter un widget Autocomplete
Le widget Autocomplete crée un champ de saisie de texte sur votre page Web, fournit des prédictions de lieux dans une liste de sélection d'interface utilisateur et renvoie des détails sur le lieu en réponse à une requête getPlace(). Chaque entrée de la liste de sélection correspond à un seul lieu (comme défini par l'API Places).
Le constructeur Autocomplete utilise deux arguments :
Un élément HTML input de type text. Il s'agit du champ d'entrée que le service de saisie semi-automatique surveille et auquel il associe ses résultats.
Un argument AutocompleteOptions facultatif, qui peut contenir les propriétés suivantes :
Tableau de données fields à inclure dans la réponse Place Details pour le PlaceResult sélectionné par l'utilisateur. Si la propriété n'est pas définie ou si ['ALL'] est transmis, tous les champs disponibles sont renvoyés et facturés (non recommandé pour les déploiements de production). Pour obtenir la liste des champs, consultez PlaceResult.
Tableau de types qui spécifie un type explicite ou une collection de types, listés dans les types compatibles. Si aucun type n'est spécifié, tous les types sont renvoyés.
bounds est un objet google.maps.LatLngBounds qui indique la zone dans laquelle rechercher des lieux. Les résultats sont pondérés en faveur des lieux situés entre ces limites, mais n'y sont pas restreints.
strictBounds est un boolean qui indique si l'API doit renvoyer uniquement les lieux qui se trouvent strictement dans la région définie par l'élément bounds donné. L'API ne renvoie pas de résultats en dehors de cette région, même s'ils correspondent à l'entrée utilisateur.
componentRestrictions permet de limiter les résultats à des groupes spécifiques. Actuellement, vous pouvez utiliser componentRestrictions pour filtrer jusqu'à cinq pays. Les pays doivent être transmis sous la forme d'un code pays à deux caractères conforme à la norme ISO 3166-1 Alpha-2. La liste des codes pays doit contenir plusieurs pays.
Remarque : Si vous recevez des résultats inattendus avec un code de pays, vérifiez que vous utilisez un code qui inclut les pays, les territoires dépendants et les zones spéciales d'intérêt géographique souhaités. Vous trouverez des informations sur le code sur la page Wikipédia : Liste des codes pays ISO 3166 ou sur la plate-forme de navigation en ligne ISO.
placeIdOnly permet de demander au widget Autocomplete de ne récupérer que les ID de lieu. Lorsque vous appelez getPlace() sur l'objet Autocomplete, le PlaceResult renvoyé ne disposera que des propriétés place id, types et name. Vous pouvez utiliser l'identifiant de lieu renvoyé lors de vos appels vers les services Places, Geocoding, Directions ou Distance Matrix.
Limiter les prédictions de saisie semi-automatique
Par défaut, Place Autocomplete présente tous les types de lieux, avec une pondération en faveur des prédictions de lieux proches de l'utilisateur, et extrait tous les champs de données disponibles pour le lieu qu'il sélectionne. Définissez des options Place Autocomplete pour présenter des prédictions plus pertinentes en fonction de votre cas d'utilisation.
Définir les options pendant la construction
Le constructeur Autocomplete accepte un paramètre AutocompleteOptions pour définir des contraintes lors de la création du widget. L'exemple suivant définit les options bounds, componentRestrictions et types pour demander des lieux de type establishment. Cela permet de privilégier ceux situés dans la zone géographique spécifiée et de limiter les prédictions aux États-Unis uniquement. L'option fields permet de spécifier les informations à renvoyer à propos du lieu sélectionné par l'utilisateur.
Appelez setOptions() pour modifier la valeur d'une option pour un widget existant.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
north: center.lat + 0.1,
south: center.lat - 0.1,
east: center.lng + 0.1,
west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
bounds: defaultBounds,
componentRestrictions: { country: "us" },
fields: ["address_components", "geometry", "icon", "name"],
strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
Spécifiez des champs de données afin d'éviter d'être facturé pour des SKU Places Data dont vous n'avez pas besoin. Incluez la propriété fields dans les AutocompleteOptions transmis au constructeur de widget, comme indiqué dans l'exemple précédent, ou appelez setFields() sur un objet Autocomplete existant.
Définir des pondérations et des limites de zone de recherche pour la saisie semi-automatique
Vous pouvez pondérer les résultats de la saisie semi-automatique pour privilégier un lieu ou une zone approximative. Plusieurs méthodes sont pour cela disponibles :
Définir des limites au moment de la création de l'objet Autocomplete
Modifier les limites d'un élément Autocomplete existant
Définir les limites sur la fenêtre d'affichage de la carte
Restreindre la recherche aux limites
Limiter la recherche à un pays en particulier
L'exemple précédent montre comment définir des limites lors de la création. Les exemples suivants illustrent d'autres techniques de pondération.
Modifier les limites d'une saisie semi-automatique existante
Appelez setBounds() pour remplacer la zone de recherche d'un Autocomplete existant par des limites rectangulaires.
Définissez l'option strictBounds pour restreindre les résultats aux limites actuelles, que ce soit en fonction de la fenêtre d'affichage de la carte ou des limites rectangulaires.
autocomplete.setOptions({ strictBounds: true });
Limiter les prédictions à un pays spécifique
Utilisez l'option componentRestrictions ou appelez setComponentRestrictions() pour limiter la recherche de saisie semi-automatique à un ensemble spécifique de cinq pays au maximum.
Utilisez l'option types ou appelez setTypes() pour limiter les prédictions à certains types de lieux. Cette contrainte spécifie un type ou une collection de types, comme indiqué dans Types de lieux.
Si aucune contrainte n'est spécifiée, tous les types sont renvoyés.
Pour la valeur de l'option types ou la valeur transmise à setTypes(), vous pouvez spécifier soit :
Lorsqu'un utilisateur sélectionne un lieu parmi les prédictions associées au champ de texte de saisie semi-automatique, le service déclenche un événement place_changed. Pour obtenir plus d'informations sur un lieu :
Créez un gestionnaire d'événements pour l'événement place_changed, puis appelez addListener() sur l'objet Autocomplete pour ajouter le gestionnaire.
Appelez Autocomplete.getPlace() sur l'objet Autocomplete pour récupérer un objet PlaceResult. Vous pouvez ensuite l'utiliser pour obtenir plus d'informations sur le lieu sélectionné.
Par défaut, lorsqu'un utilisateur sélectionne un lieu, la saisie semi-automatique renvoie tous les champs de données disponibles pour ce lieu. Des frais vous sont facturés en conséquence.
Utilisez Autocomplete.setFields() pour spécifier les champs de données de lieu à renvoyer. Obtenez plus d'informations sur l'objet PlaceResult, y compris la liste des champs de données de lieu que vous pouvez demander. Pour éviter d'être facturé pour des données dont vous n'avez pas besoin, vérifiez que vous utilisez Autocomplete.setFields() pour ne spécifier que les données de lieu que vous utiliserez.
La propriété name contient la description des prédictions Places Autocomplete. Pour en savoir plus sur description, consultez la documentation Places Autocomplete.
Pour les formulaires d'adresse, il est utile d'obtenir l'adresse dans un format structuré. Pour renvoyer l'adresse structurée du lieu sélectionné, appelez Autocomplete.setFields() et spécifiez le champ address_components.
L'exemple suivant utilise la saisie semi-automatique pour renseigner les champs d'un formulaire d'adresse.
TypeScript
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// Get each component of the address from the place details,
// and then fill-in the corresponding field on the form.
// place.address_components are google.maps.GeocoderAddressComponent objects
// which are documented at http://goo.gle/3l5i5Mr
for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
// @ts-ignore remove once typings fixed
const componentType = component.types[0];
switch (componentType) {
case "street_number": {
address1 = `${component.long_name} ${address1}`;
break;
}
case "route": {
address1 += component.short_name;
break;
}
case "postal_code": {
postcode = `${component.long_name}${postcode}`;
break;
}
case "postal_code_suffix": {
postcode = `${postcode}-${component.long_name}`;
break;
}
case "locality":
(document.querySelector("#locality") as HTMLInputElement).value =
component.long_name;
break;
case "administrative_area_level_1": {
(document.querySelector("#state") as HTMLInputElement).value =
component.short_name;
break;
}
case "country":
(document.querySelector("#country") as HTMLInputElement).value =
component.long_name;
break;
}
}
address1Field.value = address1;
postalField.value = postcode;
// After filling the form with address components from the Autocomplete
// prediction, set cursor focus on the second address line to encourage
// entry of subpremise information such as apartment, unit, or floor number.
address2Field.focus();
}
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// Get each component of the address from the place details,
// and then fill-in the corresponding field on the form.
// place.address_components are google.maps.GeocoderAddressComponent objects
// which are documented at http://goo.gle/3l5i5Mr
for (const component of place.address_components) {
// @ts-ignore remove once typings fixed
const componentType = component.types[0];
switch (componentType) {
case "street_number": {
address1 = `${component.long_name} ${address1}`;
break;
}
case "route": {
address1 += component.short_name;
break;
}
case "postal_code": {
postcode = `${component.long_name}${postcode}`;
break;
}
case "postal_code_suffix": {
postcode = `${postcode}-${component.long_name}`;
break;
}
case "locality":
document.querySelector("#locality").value = component.long_name;
break;
case "administrative_area_level_1": {
document.querySelector("#state").value = component.short_name;
break;
}
case "country":
document.querySelector("#country").value = component.long_name;
break;
}
}
address1Field.value = address1;
postalField.value = postcode;
// After filling the form with address components from the Autocomplete
// prediction, set cursor focus on the second address line to encourage
// entry of subpremise information such as apartment, unit, or floor number.
address2Field.focus();
}
window.initAutocomplete = initAutocomplete;
Par défaut, le champ de texte créé par le service de saisie semi-automatique contient un texte de remplacement standard. Pour modifier le texte, définissez l'attribut placeholder sur l'élément input :
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Remarque : Le texte de remplacement par défaut est automatiquement localisé. Si vous spécifiez votre propre valeur d'espace réservé, vous devez gérer sa localisation dans votre application. Pour savoir comment l'API Google Maps JavaScript détermine la langue à utiliser, veuillez consulter la documentation sur la localisation.
SearchBox permet aux utilisateurs d'effectuer une recherche géographique textuelle, comme "pizza à New York" ou "magasins de chaussures près de Robson Street".
Vous pouvez associer SearchBox à un champ de texte. À mesure que l'utilisateur saisit du texte, le service renvoie des prédictions sous la forme d'une liste de sélection déroulante.
SearchBox fournit une liste étendue de prédictions, qui peut inclure des lieux (comme défini par l'API Places) ainsi que des suggestions de termes de recherche. Par exemple, si l'utilisateur saisit "pizza à new", la liste de sélection peut proposer "pizza à New York, NY", ainsi que le nom de plusieurs pizzerias. Lorsqu'un utilisateur sélectionne un lieu dans la liste, les informations sur ce lieu sont renvoyées à l'objet SearchBox et peuvent être récupérées par votre application.
Le constructeur SearchBox utilise deux arguments :
Un élément HTML input de type text. Il s'agit du champ d'entrée que le service SearchBox surveille et auquel il associe ses résultats.
Un argument options, qui peut contenir la propriété bounds : bounds est un objet google.maps.LatLngBounds qui indique la zone dans laquelle rechercher des lieux. Les résultats sont orientés vers les lieux situés entre ces limites, mais n'y sont pas restreints.
Le code suivant utilise les paramètres de limite pour orienter les résultats vers des lieux situés dans une zone géographique spécifique définie via ses coordonnées de latitude/longitude.
var defaultBounds = new google.maps.LatLngBounds(
new google.maps.LatLng(-33.8902, 151.1759),
new google.maps.LatLng(-33.8474, 151.2631));
var input = document.getElementById('searchTextField');
var searchBox = new google.maps.places.SearchBox(input, {
bounds: defaultBounds
});
Modification de la zone de recherche pour SearchBox
Pour modifier la zone de recherche d'un objet SearchBox existant, appelez setBounds() sur l'objet SearchBox et transmettez l'objet LatLngBounds pertinent.
Lorsque l'utilisateur sélectionne un élément parmi les prédictions associées au champ de recherche, le service déclenche un événement places_changed. Vous pouvez appeler getPlaces() sur l'objet SearchBox pour récupérer un tableau contenant plusieurs prédictions, chacune étant un objet PlaceResult.
// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
const places = searchBox.getPlaces();
if (places.length == 0) {
return;
}
// Clear out the old markers.
markers.forEach((marker) => {
marker.setMap(null);
});
markers = [];
// For each place, get the icon, name and location.
const bounds = new google.maps.LatLngBounds();
places.forEach((place) => {
if (!place.geometry || !place.geometry.location) {
console.log("Returned place contains no geometry");
return;
}
const icon = {
url: place.icon as string,
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),
};
// Create a marker for each place.
markers.push(
new google.maps.Marker({
map,
icon,
title: place.name,
position: place.geometry.location,
})
);
if (place.geometry.viewport) {
// Only geocodes have viewport.
bounds.union(place.geometry.viewport);
} else {
bounds.extend(place.geometry.location);
}
});
map.fitBounds(bounds);
});
// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
const places = searchBox.getPlaces();
if (places.length == 0) {
return;
}
// Clear out the old markers.
markers.forEach((marker) => {
marker.setMap(null);
});
markers = [];
// For each place, get the icon, name and location.
const bounds = new google.maps.LatLngBounds();
places.forEach((place) => {
if (!place.geometry || !place.geometry.location) {
console.log("Returned place contains no geometry");
return;
}
const icon = {
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),
};
// Create a marker for each place.
markers.push(
new google.maps.Marker({
map,
icon,
title: place.name,
position: place.geometry.location,
}),
);
if (place.geometry.viewport) {
// Only geocodes have viewport.
bounds.union(place.geometry.viewport);
} else {
bounds.extend(place.geometry.location);
}
});
map.fitBounds(bounds);
});
Récupération programmatique des prédictions du service Place Autocomplete
Pour récupérer des prédictions de manière programmatique, utilisez la classe AutocompleteService. AutocompleteService n'ajoute aucune commande d'interface utilisateur. Il renvoie à la place un tableau d'objets de prédiction, contenant chacun le texte de la prédiction ainsi que des informations de référence et des détails sur la manière dont les résultats correspondent à l'entrée utilisateur.
Cette approche est utile si vous souhaitez mieux contrôler l'interface utilisateur qu'avec les méthodes Autocomplete et SearchBox décrites ci-dessus.
AutocompleteService expose les méthodes suivantes :
getPlacePredictions() renvoie des prédictions de lieux.
Remarque : Comme défini par l'API Places, un "lieu" peut être un établissement, un point géographique ou un point d'intérêt.
getQueryPredictions() renvoie une liste étendue de prédictions, qui peut inclure des lieux (comme défini par l'API Places) ainsi que des suggestions de termes de recherche. Par exemple, si l'utilisateur saisit "pizza à new", la liste de sélection peut proposer "pizza à New York, NY", ainsi que le nom de plusieurs pizzerias.
Les deux méthodes ci-dessus renvoient un tableau d'objets de prédiction au format suivant :
description est la prédiction correspondante.
distance_meters est la distance en mètres du lieu à partir du AutocompletionRequest.origin spécifié.
matched_substrings contient un ensemble de sous-chaînes dans la description qui correspondent aux éléments de l'entrée utilisateur. Cela peut être utile pour mettre en avant ces sous-chaînes dans votre application. Dans de nombreux cas, la requête apparaîtra en tant que sous-chaîne du champ de description.
length est la longueur de la sous-chaîne.
offset est le décalage de caractères, mesuré à partir du début de la chaîne de description, auquel la sous-chaîne correspondante apparaît.
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 le champ placeId d'une requête Places Details. Découvrez comment référencer un lieu avec un ID de lieu.
terms est un tableau contenant des éléments de la requête. Pour un lieu, chaque élément constitue généralement une partie de l'adresse.
offset est le décalage de caractères, mesuré à partir du début de la chaîne de description, auquel la sous-chaîne correspondante apparaît.
value est le terme correspondant.
L'exemple ci-dessous exécute une demande de prédiction de requête pour les termes "pizza near" (pizza près de) et affiche les résultats dans une liste.
TypeScript
// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// 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 initService(): void {
const displaySuggestions = function (
predictions: google.maps.places.QueryAutocompletePrediction[] | null,
status: google.maps.places.PlacesServiceStatus
) {
if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
alert(status);
return;
}
predictions.forEach((prediction) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
(document.getElementById("results") as HTMLUListElement).appendChild(li);
});
};
const service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
declare global {
interface Window {
initService: () => void;
}
}
window.initService = initService;
// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// 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 initService() {
const displaySuggestions = function (predictions, status) {
if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
alert(status);
return;
}
predictions.forEach((prediction) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
document.getElementById("results").appendChild(li);
});
};
const service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
window.initService = initService;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<p>Query suggestions for 'pizza near Syd':</p>
<ul id="results"></ul>
<!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
<img
class="powered-by-google"
src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
alt="Powered by Google"
/>
<!--
The `defer` attribute causes the script to execute after the full HTML
document has been parsed. For non-blocking uses, avoiding race conditions,
and consistent behavior across browsers, consider loading using Promises. See
https://developers.google.com/maps/documentation/javascript/load-maps-js-api
for more information.
-->
<script
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
defer
></script>
</body>
</html>
AutocompleteService.getPlacePredictions() peut utiliser des jetons de session (s'ils sont implémentés) pour regrouper les requêtes de saisie semi-automatique à des fins de facturation. Les jetons de session regroupent les phases de requête et de sélection d'une recherche de saisie semi-automatique d'un utilisateur dans une session distincte à des fins de facturation. La session commence lorsque l'utilisateur commence à saisir une requête et se termine lorsqu'il sélectionne un lieu. Chaque session peut comporter plusieurs requêtes, suivies d'une sélection de lieu.
Lorsque la session prend fin, le jeton n'est plus valide. Votre application doit générer un nouveau jeton pour chaque session. Nous vous recommandons d'utiliser des jetons de session pour toutes les sessions de saisie semi-automatique. Si vous omettez le paramètre sessionToken ou si vous réutilisez un jeton de session, la session est facturée comme si aucun jeton n'était fourni (chaque requête est facturée séparément).
Vous pouvez utiliser le même jeton de session pour effectuer une seule requête Place Details sur le lieu résultant d'un appel à AutocompleteService.getPlacePredictions().
Dans ce cas, la requête de saisie semi-automatique est combinée à la requête Places Details, et l'appel est facturé en tant que requête Places Details standard. La requête de saisie semi-automatique n'est pas facturée.
N'oubliez pas de transmettre un jeton de session unique pour chaque nouvelle session. Utiliser un même jeton pour plusieurs sessions de saisie semi-automatique invalidera ces sessions, et toutes les requêtes de saisie semi-automatique des sessions non valides seront facturées individuellement à l'aide du SKU Autocomplete Per Request. En savoir plus sur les jetons de session
L'exemple suivant montre comment créer un jeton de session et le transmettre dans un AutocompleteService (pour des raisons de concision, la fonction displaySuggestions() a été omise) :
// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();
// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
input: 'pizza near Syd',
sessionToken: sessionToken
},
displaySuggestions);
N'oubliez pas de transmettre un jeton de session unique pour chaque nouvelle session. Si vous utilisez le même jeton pour plusieurs sessions, chaque requête est facturée individuellement.
Par défaut, les éléments d'interface utilisateur fournis par Autocomplete et SearchBox sont stylisés pour être inclus sur une carte Google. Vous pouvez choisir d'adapter leur style à votre propre site. Les classes CSS suivantes sont disponibles. Toutes les classes listées ci-dessous s'appliquent aux widgets Autocomplete et SearchBox.
Classes CSS pour les widgets Autocomplete et SearchBox
Classe CSS
Description
pac-container
Élément visuel contenant la liste des prédictions renvoyées par le service Place Autocomplete. Cette liste apparaît sous forme de liste déroulante sous le widget Autocomplete ou SearchBox.
pac-icon
Icône affichée à gauche de chaque élément dans la liste des prédictions.
pac-item
Élément dans la liste de prédictions fourni par le widget Autocomplete ou SearchBox.
pac-item:hover
Élément qui s'affiche lorsque l'utilisateur pointe dessus.
pac-item-selected
Élément que l'utilisateur sélectionne avec le clavier. Remarque : Les éléments sélectionnés seront membres de cette classe et de la classe pac-item.
pac-item-query
Délai dans un pac-item qui constitue la partie principale de la prédiction. Pour les emplacements géographiques, cet élément contient le nom du lieu, par exemple "Sydney", ou le nom et le numéro d'une rue, comme "10 King Street". Pour les recherches textuelles comme "pizza à New York", il contient le texte complet de la requête. Par défaut, pac-item-query est coloré en noir. Si le champ pac-item contient du texte supplémentaire, il se trouve en dehors de pac-item-query et hérite son style de pac-item. Par défaut, il apparaît en gris. Le texte additionnel est généralement une adresse.
pac-matched
Partie de la prédiction renvoyée qui correspond à ce qu'a saisi l'utilisateur. Par défaut, le texte correspondant apparaît en gras. Notez que le texte correspondant peut se trouver n'importe où dans pac-item. Il ne fait pas nécessairement partie de pac-item-query, et pourrait être partiellement inclus dans pac-item-query, ainsi que dans le texte restant de pac-item.
Utiliser le composant Place Picker
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 composant Web Place Picker pour activer la saisie de texte qui permet aux utilisateurs finaux de rechercher une adresse ou un lieu spécifiques à l'aide de la saisie semi-automatique.
Figure 1 : Saisie de texte pour rechercher une adresse ou un lieu spécifiques à l'aide de la saisie semi-automatique
Optimisation de Place Autocomplete
Cette section décrit les bonnes pratiques pour vous aider à exploiter au mieux le service Place Autocomplete.
Développez dès le départ vos connaissances des champs de données Place Autocomplete essentiels.
Les champs de pondération et de restriction de lieu sont facultatifs, mais peuvent avoir un impact important sur les performances de la saisie semi-automatique.
Utilisez la gestion des erreurs pour vérifier que votre application se dégrade correctement si l'API renvoie une erreur.
Assurez-vous que votre application fonctionne lorsqu'il n'y a aucune sélection et qu'elle propose aux utilisateurs un moyen de poursuivre.
Bonnes pratiques liées à l'optimisation des coûts
Optimisation de base des coûts
Pour optimiser le coût d'utilisation du service Place Autocomplete, utilisez des masques de champ dans les widgets Place Details et Place Autocomplete afin de ne renvoyer que les champs de données de lieu dont vous avez besoin.
Optimisation avancée des coûts
Envisagez d'implémenter Place Autocomplete de manière programmatique pour accéder au tarif par requête et demander des résultats d'API Geocoding pour le lieu sélectionné plutôt que pour Place Details. La tarification par requête associée à l'API Geocoding est plus rentable que la tarification par session (basée sur la session) si les deux conditions suivantes sont remplies :
Si vous n'avez besoin que de la latitude/longitude ou de l'adresse du lieu sélectionné par l'utilisateur, l'API Geocoding fournit ces informations à un prix inférieur à celui d'un appel Place Details.
Si les utilisateurs sélectionnent une prédiction de saisie semi-automatique toutes les quatre requêtes de prédiction ou moins en moyenne, la tarification par requête peut être plus rentable que celle par session.
Pour obtenir de l'aide concernant l'implémentation de Place Autocomplete selon vos besoins, sélectionnez l'onglet correspondant à votre réponse à la question suivante.
Votre application nécessite-t-elle des informations autres que l'adresse et la latitude/longitude de la prédiction sélectionnée ?
Les coûts indiqués ici sont exprimés en USD. Pour obtenir des informations complètes sur les tarifs, consultez la page Facturation Google Maps Platform.
Bonnes pratiques liées aux performances
Les consignes suivantes décrivent les méthodes permettant d'optimiser les performances de Place Autocomplete :
Ajoutez des restrictions locales, une pondération géographique et des préférences linguistiques (pour les implémentations programmatiques) à votre implémentation Place Autocomplete. La préférence linguistique n'est pas obligatoire pour les widgets, car ils sélectionnent cette option dans le navigateur ou l'appareil mobile de l'utilisateur.
Si Place Autocomplete est accompagné d'une carte, vous pouvez pondérer la position en fonction de la fenêtre d'affichage de la carte.
Dans les cas où l'utilisateur ne choisit pas l'une des prédictions de la saisie semi-automatique, généralement parce qu'aucune d'entre elles n'est l'adresse souhaitée, vous pouvez réutiliser l'entrée utilisateur d'origine pour essayer d'obtenir des résultats plus pertinents :
Si vous pensez que l'utilisateur ne saisira que des informations d'adresse, réutilisez son entrée d'origine dans un appel à l'API Geocoding.
Si vous pensez que l'utilisateur saisira des requêtes pour un lieu spécifique avec un nom ou une adresse, utilisez une requête Find Place.
Si les résultats ne sont attendus que dans une région spécifique, utilisez la pondération géographique.
Voici d'autres scénarios dans lesquels il est préférable de revenir à l'API Geocoding :
Lorsque des utilisateurs saisissent des compléments d'adresse dans des pays où Place Autocomplete n'est pas totalement compatible avec ce type d'adresses : Estonie, Lituanie et Tchéquie, par exemple. Par exemple, l'adresse tchèque "Stroupežnického 3191/17, Praha" génère une prédiction partielle dans Place Autocomplete.
Lorsque des utilisateurs saisissent des adresses qui contiennent un préfixe identifiant une portion de route, par exemple "23-30 29th St, Queens" à New York ou "47-380 Kamehameha Hwy, Kaneohe" sur l'île de Kauai, à Hawaï.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2024/07/26 (UTC).
[null,null,["Dernière mise à jour le 2024/07/26 (UTC)."],[],[]]
