Place Autocomplete

Sélectionnez une plate-forme : Android iOS JavaScript Service Web

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 :

  1. Accédez à la console Google Cloud.
  2. 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.
  3. Dans la liste des API du tableau de bord, recherchez API Places.
  4. Si vous trouvez l'API dans la liste, vous pouvez continuer. Si l'API ne figure pas dans la liste, activez-la :
    1. 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.
    2. Recherchez l'API Places, puis sélectionnez-la dans la liste des résultats.
    3. 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.
    Champ de texte avec saisie semi-automatique et liste de sélection des prédictions de lieux fournies à mesure que l&#39;utilisateur saisit sa requête de recherche.
    Figure 1 : Champ de texte avec saisie semi-automatique et liste de sélection
    Formulaire d&#39;adresse rempli.
    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 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.
    Formulaire d&#39;adresse rempli.
    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);
index.ts

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);

index.js

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);
index.ts

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);

index.js
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);
index.ts

JavaScript

autocomplete.bindTo("bounds", map);

index.js

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 });
index.ts

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.js

Voir un exemple

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"],
});
index.ts

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

index.js

Voir un exemple

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.

Accéder à la démonstration

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 :

  1. Créez un gestionnaire d'événements pour l'événement place_changed, puis appelez addListener() sur l'objet Autocomplete pour ajouter le gestionnaire.
  2. 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();
}
index.ts

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;

index.js

Voir un exemple

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.

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.

Voir un exemple

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);
});
index.ts

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);
});
index.js

Voir un exemple

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 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;
index.ts

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;
index.js

CSS

style.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>
index.html

Essayer avec un exemple

Voir 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
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.

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.
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 ?

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 :

  1. ID de lieu figurant dans la réponse Place Autocomplete
  2. Jeton de session utilisé dans la requête Place Autocomplete
  3. 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 :

  1. ID de lieu figurant dans la réponse Place Autocomplete
  2. Jeton de session utilisé dans la requête Place Autocomplete
  3. 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.

  1. 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 :
    • Utilisateurs saisissant des adresses de sous-sites, telles que des adresses d'unités ou d'appartements spécifiques dans un immeuble. 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.