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.
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 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 :
<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.
Résumé des classes
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élection Figure 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 queAutocomplete
pour limiter la recherche. Dans le premier cas, vous pouvez orienter la recherche vers unLatLngBounds
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. - La principale différence réside dans les résultats qui s'affichent dans la liste de sélection.
- Vous pouvez créer un objet
AutocompleteService
pour récupérer des prédictions de manière programmatique. AppelezgetPlacePredictions()
pour obtenir des lieux correspondants, ougetQueryPredictions()
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 typetext
. 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éponsePlace Details
pour lePlaceResult
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, consultezPlaceResult
. - 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 objetgoogle.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 unboolean
qui indique si l'API doit renvoyer uniquement les lieux qui se trouvent strictement dans la région définie par l'élémentbounds
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 utilisercomponentRestrictions
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 widgetAutocomplete
de ne récupérer que les ID de lieu. Lorsque vous appelezgetPlace()
sur l'objetAutocomplete
, lePlaceResult
renvoyé ne disposera que des propriétésplace id
,types
etname
. Vous pouvez utiliser l'identifiant de lieu renvoyé lors de vos appels vers les services Places, Geocoding, Directions ou Distance Matrix.
- Tableau de données
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);
JavaScript
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"); 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écifier les champs de données
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.
autocomplete.setFields(["place_id", "geometry", "name"]);
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.
TypeScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
JavaScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
Définir les limites sur la fenêtre d'affichage de la carte
Utilisez bindTo()
pour orienter les résultats vers la fenêtre d'affichage de la carte, même si cette fenêtre change.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
Utilisez unbind()
pour dissocier les prédictions de saisie semi-automatique de la fenêtre d'affichage de la carte.
TypeScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
JavaScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
Restreindre la recherche aux limites actuelles
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.
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
Limiter les types de lieu
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 :
un tableau contenant jusqu'à cinq valeurs du Tableau 1 ou du Tableau 2 des Types de lieux. Exemple :
types: ['hospital', 'pharmacy', 'bakery', 'country']
soit :
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- un filtre du Tableau 3 des Types de lieux Vous ne pouvez spécifier qu'une seule valeur dans le Tableau 3.
La requête sera rejetée si :
- vous spécifiez plus de cinq types ;
- vous spécifiez des types non reconnus ;
- vous mélangez des types du Tableau 1 ou du Tableau 2 avec des filtres du Tableau 3.
La version de démonstration de Place Autocomplete montre les différences entre les types de lieux dans les prédictions.
Obtenir des informations sur un lieu
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 appelezaddListener()
sur l'objetAutocomplete
pour ajouter le gestionnaire. - Appelez
Autocomplete.getPlace()
sur l'objetAutocomplete
pour récupérer un objetPlaceResult
. 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(); }
JavaScript
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;
Personnaliser le texte d'espace réservé
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.
Pour personnaliser l'apparence des widgets, consultez Styliser les widgets Autocomplete et SearchBox.
Ajouter un widget SearchBox
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 typetext
. Il s'agit du champ d'entrée que le serviceSearchBox
surveille et auquel il associe ses résultats. - Un argument
options
, qui peut contenir la propriétébounds
:bounds
est un objetgoogle.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.
Obtenir des informations sur un lieu
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
.
Pour en savoir plus sur l'objet PlaceResult
, consultez la documentation sur les résultats des détails de lieu.
TypeScript
// 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); });
JavaScript
// 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); });
Pour personnaliser l'apparence des widgets, consultez Styliser les widgets Autocomplete et SearchBox.
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 duAutocompletionRequest.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 champplaceId
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;
JavaScript
// 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;
CSS
HTML
<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>
Essayer avec un exemple
Jetons de session
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.
En savoir plus sur les jetons de session
Styliser les widgets Autocomplete et SearchBox
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
.
![Illustration graphique des classes CSS pour les widgets Autocomplete et SearchBox](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/javascript/images/place-autocomplete-css-diagram.png?authuser=6&hl=fr)
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.
![GIF illustrant un champ de recherche. L'utilisateur commence à saisir une adresse dans le champ, et une liste déroulante contenant des adresses associées s'affiche. L'utilisateur clique sur une adresse dans la liste déroulante, et le reste de l'adresse est ajouté dans le champ de recherche.](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/javascript/images/place-picker.gif?authuser=6&hl=fr)
Optimisation de Place Autocomplete
Cette section décrit les bonnes pratiques pour vous aider à exploiter au mieux le service Place Autocomplete.
Voici quelques consignes générales :
- Le moyen le plus rapide de développer une interface utilisateur fonctionnelle consiste à utiliser le widget Autocomplete de l'API Maps JavaScript, le widget Autocomplete du SDK Places pour Android ou la commande d'interface utilisateur Autocomplete du SDK Places pour iOS.
- 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.
Votre application nécessite-t-elle des informations autres que l'adresse et la latitude/longitude de la prédiction sélectionnée ?
Oui, elle a besoin de plus d'informations
Utilisez Place Autocomplete basé sur des sessions avec Place Details
Étant donné que votre application nécessite des informations Places Details telles que le nom du lieu, l'état de l'établissement ou les horaires d'ouverture, votre implémentation de Place Autocomplete doit utiliser un jeton de session (de manière programmatique ou intégré aux widgets JavaScript, Android ou iOS) pour un coût total de 0,017 $ par session, auquel s'ajoutent les SKU Places Data en fonction des champs de données de lieu que vous demandez1.
Implémentation de widgets
La gestion de sessions est automatiquement intégrée aux widgets JavaScript, Android ou iOS. Cela inclut les requêtes Place Autocomplete et la requête Places Details pour la prédiction sélectionnée. Veillez à spécifier le paramètre fields
pour vous assurer de ne demander que les champs de données de lieu dont vous avez besoin.
Implémentation programmatique
Utilisez un jeton de session avec vos requêtes Place Autocomplete. Lorsque vous demandez des détails sur un lieu concernant la prédiction sélectionnée, incluez les paramètres suivants :
- ID de lieu figurant dans la réponse Place Autocomplete
- Jeton de session utilisé dans la requête Place Autocomplete
- Le paramètre
fields
spécifiant les champs de données de lieu dont vous avez besoin
Non, seuls les adresses et les lieux sont nécessaires
L'API Geocoding peut être une option plus rentable que Place Details pour votre application, en fonction de vos performances d'utilisation de Place Autocomplete. L'efficacité de la saisie semi-automatique varie d'une application à l'autre en fonction des informations saisies, du lieu d'utilisation de l'application et de l'implémentation des bonnes pratiques d'optimisation des performances.
Afin de répondre à la question suivante, analysez le nombre moyen de caractères saisis par un utilisateur avant qu'il sélectionne une prédiction Place Autocomplete dans votre application.
En moyenne, vos utilisateurs sélectionnent-ils une prédiction Place Autocomplete en quatre requêtes ou moins ?
Oui
Implémentez Place Autocomplete de manière programmatique sans jeton de session, puis appelez l'API Geocoding sur la prédiction de lieu sélectionnée.
L'API Geocoding fournit des adresses et des coordonnées de latitude/longitude pour 0,005 $ par requête. Le coût de quatre requêtes Place Autocomplete – Par requête est de 0,01132 $. Le coût total de quatre requêtes plus un appel de l'API Geocoding pour la prédiction de lieu sélectionnée s'élève donc à 0,01632 $, soit moins que le tarif Autocomplete par session (0,017 $ par session)1.
Pensez à appliquer les bonnes pratiques liées aux performances pour aider vos utilisateurs à obtenir la prédiction qu'ils recherchent en utilisant moins de caractères.
Non
Utilisez Place Autocomplete basé sur des sessions avec Place Details
Étant donné que le nombre moyen de requêtes que vous prévoyez d'effectuer avant qu'un utilisateur ne sélectionne une prédiction Place Autocomplete dépasse le coût par session, votre implémentation de Place Autocomplete doit utiliser un jeton de session pour les requêtes Place Autocomplete et la requête Place Details associée, pour un coût total de 0,017 $ par session1.
Implémentation de widgets
La gestion de sessions est automatiquement intégrée aux widgets JavaScript, Android ou iOS. Cela inclut les requêtes Place Autocomplete et la requête Places Details pour la prédiction sélectionnée. Veillez à spécifier le paramètre fields
afin de vous assurer de ne demander que les champs Données de base.
Implémentation programmatique
Utilisez un jeton de session avec vos requêtes Place Autocomplete. Lorsque vous demandez des détails sur un lieu concernant la prédiction sélectionnée, incluez les paramètres suivants :
- ID de lieu figurant dans la réponse Place Autocomplete
- Jeton de session utilisé dans la requête Place Autocomplete
- Paramètre
fields
spécifiant les champs de données de base comme l'adresse et la géométrie
Envisagez de reporter les requêtes Place Autocomplete
Vous pouvez appliquer des stratégies telles que le report d'une requête Place Autocomplete jusqu'à ce que l'utilisateur ait saisi les trois ou quatre premiers caractères. Votre application enverra ainsi moins de requêtes. Par exemple, si vous effectuez des requêtes Place Autocomplete pour chaque caractère après que l'utilisateur a saisi le troisième caractère, s'il en saisit sept, puis sélectionne une prédiction pour laquelle vous effectuez une requête API Geocoding, le coût total sera de 0,01632 $ (4 x 0,00283 $ pour la saisie semi-automatique par requête + 0,005 $ pour Geocoding)1.
Si, à cause du report de requêtes, votre requête programmatique moyenne est inférieure à quatre, vous pouvez suivre les instructions pour intégrer efficacement Place Autocomplete à l'API Geocoding. Notez que les requêtes reportées peuvent être perçues comme de la latence par l'utilisateur, qui peut s'attendre à voir des prédictions à chaque nouvelle frappe.
Pensez à appliquer les bonnes pratiques liées aux performances pour aider vos utilisateurs à obtenir la prédiction qu'ils recherchent en utilisant moins de caractères.
-
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.
- 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ï.
Limites d'utilisation et règles
Quotas
Pour obtenir des informations sur les quotas et les tarifs, consultez la documentation sur l'utilisation et la facturation de l'API Places.
Règles
L'utilisation de la bibliothèque Places et de l'API Maps JavaScript doit respecter les Règles relatives à l'API Places.