Mettre en œuvre et optimiser Google Place Autocomplete avec Places Library
Sommaire
L'API Google Places renvoie des informations et des suggestions sur des lieux — commerces, adresses et points d'intérêt. Elle peut être utilisée pour proposer une fonctionnalité d'autocomplete dans les recherches géographiques textuelles, en retournant des suggestions au fur et à mesure que l'utilisateur frappe. Google met à disposition une bibliothèque Places via l'API JavaScript Maps.
Cet article de blog se concentre sur l'utilisation de cette bibliothèque et sur la façon d'implémenter vous-même l'autocomplete Google Places via l'API.
Implémenter l'autocomplete avec l'API Google Places
Comment activer l'API Google Places et obtenir une clé API
Avant d'utiliser la bibliothèque Places dans l'API JavaScript Maps, vous devez d'abord activer l'API Places dans la console Google Cloud Platform. Voici la procédure à suivre :
- Accédez à la console Google Cloud Platform.
- Créez un nouveau projet ou sélectionnez un projet existant.
- En haut de la page, cliquez sur le bouton ACTIVER DES API ET DES SERVICES.
- Recherchez l'API Places, puis sélectionnez-la dans la liste de résultats.
- Cliquez sur ACTIVER. Une fois l'opération terminée, l'API Places apparaîtra dans la liste des API du tableau de bord.
N'oubliez pas d'appliquer des restrictions d'application (pour limiter l'utilisation aux API concernées — au minimum l'API Places) et des restrictions d'API (pour autoriser l'utilisation de cette API via des domaines spécifiques). Nous expliquons comment restreindre une clé API Google Places à un domaine spécifique dans cet article.
Découvrez d'autres solutions : Woosmap Localities ou Woosmap Address Finder.
Comment charger la bibliothèque Google Places
Pour utiliser l'autocomplete, vous devez d'abord charger la bibliothèque Google Places via le paramètre libraries dans l'URL d'initialisation de l'API JavaScript Google Maps. Vous pouvez le faire avec le code suivant :
<script type= "text/javascript" src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"></script>Maintenant que nous avons vu comment activer l'API Google Places et charger la bibliothèque, penchons-nous sur les widgets proposés.
Les widgets de l'API Google Places
L'API Places propose deux types de widgets d'autocomplétion, accessibles respectivement via les classes Autocomplete et SearchBox.
Le widget Autocomplete
autocomplete=new google.maps.places.Autocomplete(input, options);L'autocomplétion ajoute un champ de saisie à votre page web. Au fil de la frappe, le service retourne des suggestions de lieux sous forme de liste déroulante. Lorsque l'utilisateur sélectionne un lieu, les détails correspondants sont renvoyés en réponse à une requête getPlace(). Chaque entrée de la liste correspond à un lieu unique (au sens de la Places API). La recherche peut être restreinte à un pays et à des types de lieux spécifiques, avec la possibilité de définir des limites géographiques.
Dans l'exemple ci-dessous, recherchez « Old Coff » et sélectionnez le premier résultat (Old Coffee House). Les résultats sont orientés vers les limites actuelles de la carte via autocomplete.bindTo('bounds', map). Pour que le service Places Autocomplete retourne* uniquement* des résultats dans cette zone, activez l'option strictbounds: true.
The SearchBox Widget
searchBox = new google.maps.places.SearchBox(input, options);SearchBox ajoute un champ de saisie de texte à votre page web, de manière similaire à Autocomplete. La différence principale réside dans les résultats qui apparaissent dans la liste déroulante. SearchBox fournit une liste étendue de prédictions, qui peut inclure des lieux (tels que définis par l'API Places) ainsi que des termes de recherche suggérés. SearchBox offre moins d'options qu'Autocomplete pour restreindre la recherche. Vous pouvez uniquement orienter la recherche vers un LatLngBounds donné.
Dans l'exemple ci-dessous, recherchez « Coffee near Lond » et sélectionnez le premier terme de recherche suggéré dans la liste déroulante.
Découvrez comment intégrer une carte dans une page web.
Comment créer un objet AutocompleteService
service = new google.maps.places.AutocompleteService();service.getQueryPredictions({ input: 'hotels near Lond' }, function(predictions, status){});Vous pouvez créer un objet AutocompleteService pour récupérer des prédictions par programmation. Appelez getPlacePredictions() pour récupérer les lieux correspondants, ou getQueryPredictions() pour récupérer les lieux correspondants ainsi que les termes de recherche suggérés. AutocompleteService n'ajoute aucun contrôle d'interface utilisateur. Les méthodes ci-dessus renvoient à la place 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 façon dont le résultat correspond à la saisie de l'utilisateur. Cela est utile si vous souhaitez un contrôle plus fin sur l'interface utilisateur que ce qu'offrent les fonctionnalités Autocomplete et SearchBox décrites ci-dessus.
Pour obtenir la localisation et plus d'informations sur l'un des lieux renvoyés (par exemple, lorsqu'un utilisateur sélectionne un lieu dans la liste déroulante), vous devez envoyer une requête Place Details avec getDetails(request, callback) en spécifiant le place_id et les champs souhaités.
Dans l'exemple ci-dessous, recherchez « Old Coff » et sélectionnez le premier élément de la liste déroulante (Old Coffee House).
How to optimise your usage cost of Autocomplete in the Google Places API
There are several different solutions to help you reduce the cost of your Google Places licence.
Data return for specific fields in detailed location queries
When the Places Autocomplete service returns results from a search, it places them within a predictions array. Each prediction result contains the following fields: description, place_id, terms, types, matched_substrings, structured_formatting. You can read more about the fields included in prediction results here.
By default, when a user selects a place from the pick list, autocomplete returns all of the available data fields for the selected place, and you are billed for all of them, even the ones you don’t need. You can customise Place Detail requests to return data only for specific fields used in your application and, which will decrease the cost of your Places API License. These fields are divided into three categories: Basic, Contact, and Atmosphere. Let’s take a closer look at what is included in each one.
Basic
The Basic category includes the following fields: address_component, adr_address, formatted_address, geometry, icon, name, permanently_closed, photo, place_id, plus_code, type, url, utc_offset, vicinity
Contact
The Contact category includes the following fields: formatted_phone_number, international_phone_number, opening_hours, website
Atmosphere
The Atmosphere category includes the following fields: price_level, rating, review, user_ratings_total
How can I specify my desired data?
For example, to retrieve only the geometry field in the details response (when user select an item in the pick list), define as below:
Places Autocomplete widget: use autocomplete.setFields(['geometry']). check the jsFiddle above to see how.
Places SearchBox widget: there is no way to constrain SearchBox requests to only return specific fields.
Places AutocompleteService: you have to use the PlacesService to call the getDetails(request, callback) and specify the fields in your request parameter.
let request = {
placeId: place_id,
fields: ['geometry']
}
Session token or per query
If you are using the Autocomplete Widget, you don’t need to implement sessions, as the widget handles sessions automatically in the background.
The Per Request is the default billing option when you use AutocompleteService. Charges are applied per keystroke, which can lead to higher billings.
You should use Session Tokens when implementing AutocompleteService.getPlacePredictions() to group together autocomplete requests for billing purposes. Session tokens group the query and selection phases of a user’s autocomplete search into a discrete session for billing purposes. The session begins when the user starts typing a query, and concludes when they select a place. Each session can have multiple queries, followed by one place selection.
The following example shows a request using the sessiontoken parameter:
// Create a new session token.let sessionToken = new google.maps.places.AutocompleteSessionToken();// Pass the token to the autocomplete service.let autocompleteService = new google.maps.places.AutocompleteService();autocompleteService.getPlacePredictions({ input: 'Coffee near Lond', sessionToken: sessionToken}, displaySuggestions);How to use the Geocoding API
If your application handles user-typed addresses, the addresses are sometimes ambiguous (incomplete, misspelt, or poorly formatted). You can disambiguate addresses using Autocomplete. Then, use the place IDs to get the place locations.
If you have an exact address (or close to it), however, you can reduce costs by using Geocoding instead of Autocomplete. You could for example use the AutocompleteService to get the exact address name and then execute a geocoding request to get the geometry and other desired fields (instead of AutocompleteService.getDetails()). See Geocoding API best practices.
Using debounce and minChar with AutocompleteService
The debounce function limits the rate at which a function can fire. It takes at least 2 arguments, the input function to call and a time to wait before calling it. As long as this method continues to be invoked, the function passed as a parameter will not be triggered. It will be called only after the debounce function stops being called for an elapsed time (in milliseconds).
function debounce(func, wait, immediate) { var timeout; return function() { var context = this, args = arguments; var later = function() { timeout = null; if (!immediate) func.apply(context, args); }; var callNow = immediate && !timeout; clearTimeout(timeout); timeout = setTimeout(later, wait); if (callNow) func.apply(context, args); };};Les widgets Autocomplete et SearchBox n'implémentent pas de méthode de debounce. Chaque frappe clavier déclenche donc un appel à AutocompleteService.
Pour compléter ce mécanisme, vous pouvez combiner vos appels avec un paramètre minChar afin de ne déclencher l'autocomplete que lorsque la saisie atteint au moins X caractères.
autocomplete_input.addEventListener('input', debounce(function() { let value = this.value; if (value.length > 2) { //call here autocompleteService.getPlacePredictions() }}, 150)); Using Google Places Autocomplete on stores
If your main goal to implement Google Places Autocomplete is to help your users find the right store for them, why not combine an autocompletion of your store's information (name and city for example) before possibly falling back to the Google Places Autocomplete.
If you're a Woosmap customer and already have your stores hosted on our own, you could use the Woosmap Store Search API to achieve this.
Call to action: Learn more about our Store Search API
To easily implement such a solution, have a look at Woosmap MultiSearch Lib. This small JavaScript library is designed to return location suggestions by calling several autocomplete services. It enables you to combine stores search and Google Places APIs (Places Autocomplete and Places Details). Moreover, the library natively implements the debounce and minChars mechanisms.
If your users are more likely to search for specific postal codes or localities, MultiSearch can also retrieve suggestions from Woosmap Localities.
Create a free Woosmap account for your organisation
How MultiSearch combines autocomplete services?
Autocomplete services are requested in your desired order.
By comparing the user input to the returned results and computing a string matching score between these two values, the library can automatically switch to the next autocomplete service and thereby provide suggestions that better suit your needs.
For more details, read our fallback autocomplete services concept documents.
Fallback Example with MultiSearch
The following autocomplete example is for Starbucks coffee shops. If no results are available (insufficient matching score between the field name of Starbucks coffee shops and the user input), a Google Places Autocomplete is performed.
In the sample below, search for "London" and select one of the coffee shops suggestions in the pick list.
If you search for "Coleman Coffee", the autocomplete will fall back on Google Places (there is no Starbucks coffee with this name).
Google Place Autocomplete Best Practices
To optimise your usage of Google Place Autocomplete, we recommend following these guidelines:
Prefer using the AutocompleteService instead of the Widgets to gain fine-grained control over the available optimizations.
Use the Per Session billing option.
Gather only required fields when getting details of a place.
Implement Debounce and minChars mechanisms.
Use the Geocoding API to retrieve address information instead of getDetails() from Autocomplete.
Alternatively, offer to autocomplete your store's information if the first use case is to help users find them.
The last example implements Woosmap MultiSearch with Google AutocompleteService, per Session billing, Debounce, and autocomplete on Stores before falling back to Google. This could be a good entry point for dealing with Google Place Autocomplete.
Conclusion
We have now covered how to implement the Google Places API and some strategies to ensure you receive the data you are looking for while optimising your costs.
If you have any questions about using autocomplete with the Google Places API, please don’t hesitate to reach out to us through the contact page. We are always interested to hear your feedback and suggestions!