Place Autocomplete

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.
Sélectionnez une plate-forme : Android iOS JavaScript Service Web

Présentation

Autocomplete est une fonctionnalité de la bibliothèque Places de l'API Maps JavaScript. Vous pouvez utiliser la saisie semi-automatique pour indiquer à vos applications le comportement de recherche anticipée du champ de recherche Google Maps. Le service de saisie semi-automatique peut établir une correspondance avec des mots et des sous-chaînes complets, ce qui résout les noms de lieu, les adresses et les plus codes. Les applications peuvent donc envoyer des requêtes au fur et à mesure de la saisie pour fournir des prédictions de lieux.

Premiers pas

Avant d'utiliser la bibliothèque Places dans l'API Maps JavaScript, assurez-vous qu'elle est activée dans Google Cloud Console, dans le projet que vous avez configuré pour l'API Maps JavaScript.

Pour afficher la liste des API activées :

  1. Accédez à Google Cloud Console.
  2. Cliquez sur le bouton Sélectionner un projet, puis sélectionnez le projet que vous avez configuré pour l'API Maps JavaScript et 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 API Places, puis sélectionnez-la dans la liste des résultats.
    3. Sélectionnez ACTIVER. Une fois le processus terminé, 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&libraries=places&callback=initMap">
</script>

Pour en savoir plus, consultez la page 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 automatisée les résultats de la saisie semi-automatique (consultez la documentation de référence de l'API Maps JavaScript : Classe AutocompleteService).

Voici un résumé des classes disponibles :

  • Autocomplete ajoute un champ de saisie de texte à votre page Web et surveille ce champ pour les entrées de caractères. Lorsque l'utilisateur saisit du texte, la saisie semi-automatique renvoie des prédictions de lieu sous la forme d'une liste déroulante de sélection. Lorsque l'utilisateur sélectionne un lieu dans la liste, les informations sur ce 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 lorsque 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, de la même manière que Autocomplete. Les différences sont les suivantes :
    • La principale différence réside dans les résultats qui apparaissent 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 "pizzeria à lyon", la liste peut contenir l'expression "pizza lyon à Brest", ainsi que les noms des différentes pizzerias.
    • SearchBox propose moins d'options que Autocomplete pour limiter la recherche. Dans le premier cas, vous pouvez limiter la recherche à un LatLngBounds donné. Dans ce dernier cas, vous pouvez limiter la recherche à un pays et à des types de lieux particuliers, et définir des limites. Pour en savoir plus, consultez ci-dessous.
    Formulaire d&#39;adresse rempli.
    Figure 3: un champ de recherche présente des termes de recherche et des prédictions de lieux.
    Pour en savoir plus, consultez les informations ci-dessous.
  • Vous pouvez créer un objet AutocompleteService pour récupérer des prédictions de manière automatisée. Appelez getPlacePredictions() pour obtenir des lieux correspondants, ou getQueryPredictions() pour récupérer des lieux correspondants et des suggestions de termes de recherche. Remarque: AutocompleteService n'ajoute aucune commande d'interface utilisateur. À la place, la méthode ci-dessus renvoie 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 correspondance entre le résultat et l'entrée 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 (tel que 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 de saisie que le service de saisie semi-automatique surveillera et auquel il associera 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 l'utilisateur sélectionné PlaceResult. Si la propriété n'est pas définie ou si ['ALL'] est transmis, tous les champs disponibles sont renvoyés et facturés (cette option n'est pas recommandée 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, comme indiqué dans les types compatibles. Si aucun type n'est spécifié, tous les types sont renvoyés.
    • bounds est un objet google.maps.LatLngBounds spécifiant la zone dans laquelle rechercher des lieux. Les résultats sont orientés vers les lieux compris dans ces limites, sans s'y limiter.
    • strictBounds est un boolean spécifiant 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 si ceux-ci 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 indiqués sous la forme d'un code pays à deux caractères conforme à la norme ISO 3166-1 Alpha-2. La liste des codes pays doit comporter 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 que vous souhaitez. 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. Lors de l'appel de getPlace() sur l'objet Autocomplete, les propriétés place id, types et name rendues par PlaceResult ne sont disponibles. Vous pouvez utiliser l'ID de lieu renvoyé avec les appels aux services Places, Geocoding, Directions ou Distance Matrix.

Limiter les prédictions de la saisie semi-automatique

Par défaut, Place Autocomplete présente tous les types de lieux, pondérés pour les prédictions à proximité de l'emplacement de l'utilisateur, et extrait tous les champs de données disponibles pour le lieu sélectionné par l'utilisateur. 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 de 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, ce qui permet de favoriser ceux situés dans la zone géographique spécifiée et de limiter les prédictions aux lieux situés aux États-Unis. Le paramètre fields spécifie les informations à afficher sur le 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,
  types: ["establishment"],
};

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,
  types: ["establishment"],
};
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 que des codes SKU Places Data ne vous soient facturés. Incluez la propriété fields dans le 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 biais 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 approximatif, comme suit:

  • Définissez les limites lors de la création de l'objet Autocomplete.
  • Modifiez les limites d'un Autocomplete existant.
  • Définissez les limites sur la fenêtre d'affichage de la carte.
  • Limitez 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'un objet Autocomplete existant

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 limiter les résultats à la fenêtre d'affichage de la carte, même si celle-ci change.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Utilisez unbind() pour dissocier les prédictions de la 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 });

Voir un exemple

Limiter la recherche aux limites actuelles

Définissez l'option strictBounds pour limiter les résultats aux limites actuelles, que ce soit en fonction de la fenêtre d'affichage de la carte ou de 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 à 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"],
});

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 la section 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 l'une des valeurs suivantes:

  • Un tableau contenant jusqu'à cinq valeurs de la table 1 ou de la table 2 de l'ensemble de types de lieux Exemple :

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    Ou :

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Tout filtre du tableau 3 dans Types de lieux Vous ne pouvez spécifier qu'une seule valeur dans le tableau 3.

La demande sera rejetée si:

  • Vous spécifiez plus de cinq types.
  • Vous spécifiez tous les types non reconnus.
  • Vous mélangez n'importe quel type du Tableau 1 ou du Tableau 2 avec n'importe quel filtre du Tableau 3.

La démonstration de Places Autocomplete montre les différences entre les différents types de lieux dans les prédictions.

Accéder à la démo

Obtenir des informations sur un lieu

Lorsqu'un utilisateur sélectionne un lieu dans les prédictions associées au champ de texte de saisie semi-automatique, le service déclenche un événement place_changed. Pour obtenir des 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, que vous pouvez ensuite 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 alors facturés. Utilisez Autocomplete.setFields() pour spécifier les champs de données de lieu à afficher. 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 de payer pour des données dont vous n'avez pas besoin, veillez à utiliser Autocomplete.setFields() pour ne spécifier que les données de lieu que vous utiliserez.

La propriété name contient le 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 au 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 remplir 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;

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 du texte d'espace réservé 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: L'espace réservé par défaut est localisé automatiquement. Si vous spécifiez votre propre valeur d'espace réservé, vous devez gérer la localisation de cette valeur dans votre application. Pour savoir comment l'API Google Maps JavaScript choisit le langage à utiliser, veuillez consulter la documentation sur la localisation.

Pour personnaliser l'apparence des widgets, consultez la section Appliquer un style aux widgets Autocomplete et SearchBox.

SearchBox permet aux utilisateurs d'effectuer une recherche géographique sur du texte, comme "pizza à New York" ou "magasins de chaussures à proximité de Robson Street". Vous pouvez associer SearchBox à un champ de texte et, à mesure que vous saisissez du texte, le service renvoie des prédictions sous la forme d'une liste déroulante 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 "pizzeria à lyon", la liste peut contenir l'expression "pizzeria à Nice" ainsi que le nom des différentes 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 de saisie que le service SearchBox surveillera et auquel il associera ses résultats.
  • Un argument options, qui peut contenir la propriété bounds : bounds est un objet google.maps.LatLngBounds spécifiant la zone dans laquelle rechercher des lieux. Les résultats sont orientés vers les lieux contenus dans ces limites, sans s'y limiter.

Le code suivant utilise le paramètre "bounds" pour pondérer les résultats en fonction des lieux situés dans une zone géographique spécifique, spécifiée via des 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 le champ de recherche

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

Voir un exemple

Pour personnaliser l'apparence des widgets, consultez la section Appliquer un style aux 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 automatisée, utilisez la classe AutocompleteService. AutocompleteService n'ajoute aucune commande d'interface utilisateur. Au lieu de cela, il renvoie un tableau d'objets de prédiction, chacun contenant le texte de la prédiction, des informations de référence et des détails sur la manière dont le résultat correspond à l'entrée utilisateur. Cette approche est utile si vous souhaitez mieux contrôler l'interface utilisateur que les méthodes Autocomplete et SearchBox décrites ci-dessus.

AutocompleteService expose les méthodes suivantes:

  • getPlacePredictions() renvoie des prédictions de lieux. Remarque: Un "lieu" peut être un établissement, un emplacement géographique ou un point d'intérêt principal, tel que défini par l'API Places.
  • getQueryPredictions() renvoie 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 "pizzeria à lyon", la liste peut contenir l'expression "pizza lyon à Brest", ainsi que le nom des différentes 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 dans l'entrée utilisateur. Cela est utile pour mettre en surbrillance ces sous-chaînes dans votre application. Dans de nombreux cas, la requête apparaît comme une sous-chaîne du champ de description.
    • length est la longueur de la sous-chaîne.
    • offset est le décalage de caractère, mesuré à partir du début de la chaîne de description, à laquelle 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 une partie de l'adresse.
    • offset est le décalage de caractère, mesuré à partir du début de la chaîne de description, à laquelle la sous-chaîne correspondante apparaît.
    • value est le terme de correspondance.

L'exemple ci-dessous exécute une requête de prédiction de requête pour l'expression 'pizza Near' et affiche le résultat 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>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

Essayer l'exemple

Voir un exemple

Jetons de session

AutocompleteService.getPlacePredictions() utilise des jetons de session 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 des utilisateurs 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. Une fois la session terminée, 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 le paramètre sessionToken est omis ou que vous réutilisez un jeton de session, la session est facturée comme si aucun jeton de session 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 Autocomplete est combinée avec 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 est offerte.

Veillez à transmettre un jeton de session unique pour chaque nouvelle session. Si vous utilisez le même jeton pour plusieurs sessions de saisie semi-automatique, celles-ci seront invalidées. Toutes les requêtes Autocomplete des sessions non valides seront facturées individuellement à l'aide du code SKU Autocomplete Per Request. En savoir plus sur les jetons de session

L'exemple suivant montre comment créer un jeton de session, puis le transmettre dans un objet 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);

Veillez à 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

Définir le style des 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 adapter le style à votre site. Les classes CSS suivantes sont disponibles. Toutes les classes répertorié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 de la liste des prédictions.
pac-item Élément dans la liste des prédictions fournies par le widget Autocomplete ou SearchBox.
pac-item:hover Élément qui s'affiche lorsque l'utilisateur le survole avec le pointeur de sa souris.
pac-item-selected Élément que l'utilisateur sélectionne au moyen du clavier. Remarque: Les éléments sélectionnés seront membres de cette classe et de la classe pac-item.
pac-item-query Un délai dans un pac-item qui est la partie principale de la prédiction. Pour les zones géographiques, il s'agit d'un nom de lieu (par exemple, Sydney) ou d'un nom de rue et d'un numéro (par exemple, "Street King"). Pour les recherches textuelles comme "pizza à New York", il contient le texte intégral 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 de son style de pac-item. Par défaut, il apparait en gris. Le texte supplémentaire 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, ce texte correspond au texte en gras. Notez que le texte correspondant peut se trouver n'importe où dans la zone pac-item. Il ne fait pas nécessairement partie de pac-item-query, et pourrait être partiellement dans pac-item-query ainsi qu'en partie dans le texte restant de pac-item.

Optimisation de Place Autocomplete

Cette section décrit les bonnes pratiques pour vous aider à tirer le meilleur parti du 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 le contrôle de l'interface utilisateur Autocomplete du SDK Places pour iOS.
  • Familiarisez-vous d'abord avec les champs de données Place Autocomplete essentiels.
  • Les champs de pondération et de restriction de la zone géographique sont facultatifs, mais peuvent avoir un impact important sur les performances de la saisie semi-automatique.
  • Utilisez la gestion des erreurs pour vous assurer que votre application se dégrade correctement si l'API renvoie une erreur.
  • Assurez-vous que votre application gère les options sans sélection et offre aux utilisateurs un moyen de poursuivre.

Bonnes pratiques en matière d'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 le programmatique Place Autocomplete pour accéder à la tarification 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 pour un appel à des adresses autres que Place Details.
  • Si les utilisateurs sélectionnent une prédiction de saisie semi-automatique dans une moyenne de quatre requêtes de prédiction de saisie semi-automatique ou moins, la tarification par requête peut s'avérer plus rentable que la tarification par session.
Pour obtenir de l'aide concernant la mise en œuvre 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, j'ai besoin de plus d'informations

Utiliser Place Autocomplete basé sur des sessions avec Place Details
Étant donné que votre application nécessite Place Details, comme le nom du lieu, l'état de l'établissement ou les horaires d'ouverture, vous devez utiliser un jeton de session (programmatique ou intégré aux widgets JavaScript, Android ou iOS) pour un coût total de 0,017 $par session plus les codes SKU Places Data applicables, selon les champs de données de lieu que vous demandez.

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 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 à propos de 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, je n'ai besoin que de l'adresse et du lieu

L'API Geocoding peut être une option plus rentable que Place Details pour votre application, en fonction des performances d'utilisation de Place Autocomplete. L'efficacité de la saisie semi-automatique dépend de l'entrée de l'application, de l'emplacement où elle est utilisée et de l'application ou non de bonnes pratiques en matière d'optimisation des performances.

Afin de répondre à la question suivante, analysez le nombre moyen de caractères saisis par un utilisateur avant de sélectionner une prédiction Place Autocomplete dans votre application.

Vos utilisateurs sélectionnent-ils en moyenne une prédiction Place Autocomplete en quatre requêtes maximum ?

Yes

Implémentez Place Autocomplete par programmation sans jetons de session et 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 total de quatre requêtes Place Autocomplete – Per Request 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 $, ce qui est inférieur au prix par session de saisie semi-automatique de 0,017 $par session1.

Envisagez d'appliquer les bonnes pratiques en matière de performances pour aider vos utilisateurs à obtenir la prédiction qu'ils recherchent en utilisant moins de caractères.

Non

Utiliser 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 Places 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 Basic Data (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 à propos de 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 tels que l'adresse et la géométrie

Envisager de retarder 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 afin que votre application envoie 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, cela signifie que s'il sélectionne sept caractères, 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 $ par requête semi-automatique + 0,005 $Geocoding).1

Si votre demande moyenne programmatique peut être inférieure à quatre, vous pouvez suivre les conseils pour l'implémentation de Place Autocomplete performante avec l'API Geocoding. Notez que les requêtes retardées peuvent être perçues comme de la latence par l'utilisateur, qui peut s'attendre à voir des prédictions à chaque nouvelle frappe.

Envisagez d'appliquer les bonnes pratiques en matière de 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 en USD. Pour obtenir toutes les informations tarifaires, consultez la page Facturation Google Maps Platform.

Bonnes pratiques en matière de 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. Aucune préférence linguistique n'est requise avec les widgets, car ils sélectionnent les préférences linguistiques 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 de ces prédictions n'est l'adresse de résultat 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, utilisez l'entrée utilisateur d'origine dans un appel à l'API Geocoding.
    • Si vous souhaitez que l'utilisateur saisit des requêtes pour un lieu spécifique en fonction de son nom ou de son 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 recourir à l'API Geocoding :
    • Utilisateurs saisissant des adresses de sous-réseaux autres que l'Australie, le Canada et la Nouvelle-Zélande. Par exemple, l'adresse américaine "123 Bowdoin St #456, Boston MA, États-Unis" n'est pas acceptée par Autocomplete. (La saisie semi-automatique n'accepte les adresses de sous-réseaux qu'en Australie, au Canada et en Nouvelle-Zélande. Les formats d'adresse acceptés dans ces trois pays sont les suivants : "9/321 Pitt Street, Sydney, Nouvelle-Galles du Sud, Australie" ou "14/19 Langana Avenue, Browns Bay, Auckland, Nouvelle-Zélande" ou "145-112 Renfrew Dr, Markham, Ontario, Canada".
    • Utilisateurs saisissant des adresses avec des préfixes de segment de route tels que "23-30 29th St, Queens" à New York ou "47-380 Kamehameha Hwy, Kaneohe" sur l'île de Kauai à Hawai.

Limites d'utilisation et politiques

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 l'API Places Library et Maps JavaScript doit respecter les Règles décrites pour l'API Places.

Selon nos conditions d'utilisation

Afficher
les logos et attributions requis

Respectez les droits d'auteur et l'attribution de Google. Assurez-vous que le logo et l'avis de droits d'auteur sont visibles, et affichez le logo « alimenté par Google » si vous utilisez des données sans carte.

En savoir plus