Widget Place Autocomplete

Développeurs de l'Espace économique européen (EEE)

Le widget Place Autocomplete crée un champ de saisie de texte, fournit des prédictions de lieu dans une liste de sélection d'UI et renvoie des détails de lieu en réponse à la sélection de l'utilisateur. Utilisez le widget Place Autocomplete pour intégrer une interface utilisateur de saisie semi-automatique complète et autonome sur votre page Web. Pour obtenir la documentation de référence complète de l'API, consultez PlaceAutocompleteElement.

Prérequis

Pour utiliser Place Autocomplete, vous devez activer l'API Places (nouvelle version) dans votre projet Google Cloud. Pour en savoir plus, consultez Commencer.

Nouveautés

Voici les améliorations que nous avons apportées à Place Autocomplete :

  • L'interface utilisateur du widget Autocomplete prend en charge la localisation régionale (y compris les langues RTL) pour l' espace réservé de saisie de texte, le logo de la liste de prédictions et les prédictions de lieux.
  • Amélioration de l'accessibilité, y compris la prise en charge des lecteurs d'écran et l'interaction avec le clavier.
  • Le widget Autocomplete renvoie la nouvelle classe Place (Place reference) pour simplifier le traitement de l'objet renvoyé.
  • Meilleure prise en charge des appareils mobiles et petits écrans.
  • Performances et apparence graphique améliorées.

Ajouter un widget de saisie semi-automatique

Le widget Autocomplete crée un champ de saisie de texte, fournit des prédictions de lieu dans une liste de sélection d'UI et renvoie des détails de lieu en réponse à un clic de l'utilisateur à l'aide de l'écouteur gmp-select. Cette section vous explique comment ajouter un widget de saisie semi-automatique à une page Web ou à une carte Google.

Ajouter un widget de saisie semi-automatique à une page Web

Pour ajouter le widget Autocomplete à une page Web, créez un nouveau google.maps.places.PlaceAutocompleteElement, puis ajoutez-le à la page comme illustré dans l'exemple suivant :

TypeScript

// Request needed libraries.
const { PlaceAutocompleteElement } =
    await google.maps.importLibrary('places');
// Create the input HTML element, and append it.
const placeAutocomplete = new PlaceAutocompleteElement();
document.body.appendChild(placeAutocomplete);

JavaScript

// Request needed libraries.
const { PlaceAutocompleteElement } =
    await google.maps.importLibrary('places');
// Create the input HTML element, and append it.
const placeAutocomplete = new PlaceAutocompleteElement();
document.body.appendChild(placeAutocomplete);

Voir l'exemple de code complet

Ajouter un widget de saisie semi-automatique à une carte

Si votre adresse de facturation se trouve en dehors de l' Espace économique européen (EEE), vous pouvez également utiliser le widget Autocomplete avec une carte Google.

Pour ajouter un widget Autocomplete à une carte, demandez d'abord les bibliothèques nécessaires, comme indiqué ci-dessous :

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

Ensuite, dans votre code HTML, imbriquez un nouvel élément gmp-place-autocomplete dans un div, puis imbriquez ce div dans un gmp-map, comme illustré dans l'exemple suivant :

<gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
    <div
        class="place-autocomplete-card"
        slot="control-inline-start-block-start">
        <gmp-place-autocomplete
            placeholder="Search for a place..."></gmp-place-autocomplete>
    </div>
</gmp-map>

Pour ajouter un widget Autocomplete à une carte de manière programmatique, créez une nouvelle google.maps.places.PlaceAutocompleteElement instance, ajoutez le PlaceAutocompleteElement à un div, puis appliquez l'attribut slot au div, comme illustré dans l'exemple suivant : 

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

// Get the map element.
const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;

// Create the PlaceAutocompleteElement instance.
const placeAutocomplete = new PlaceAutocompleteElement({});

// Create a div and append the PlaceAutocompleteElement to it.
const card = document.createElement("div");
card.appendChild(placeAutocomplete);

// Apply the slot attribute to the div.
// This positions the control in the top-left corner of the map.
card.setAttribute("slot", "control-inline-start-block-start");

// Append the div to the map element (check for null).
if (mapElement) {
    mapElement.appendChild(card);
}

Voir l'exemple de code complet

Ajouter un texte d'espace réservé

Utilisez la placeholder propriété pour ajouter un texte d'espace réservé. L'exemple suivant montre comment définir le texte d'espace réservé en HTML :

<gmp-place-autocomplete
  placeholder="Search for a place..."
></gmp-place-autocomplete>

Vous pouvez également définir le texte d'espace réservé de manière programmatique :

placeAutocomplete.placeholder = 'Search for a place...';

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 PlaceAutocompleteElementOptions pour présenter des prédictions plus pertinentes en limitant ou en pondérant les résultats.

Si vous limitez les résultats, le widget de saisie semi-automatique ignore tous les résultats en dehors de la zone de restriction. Une pratique courante consiste à limiter les résultats aux limites de la carte. Pondérer la saisie semi-automatique permet d'afficher les résultats dans la zone spécifiée. Toutefois, certaines correspondances peuvent se trouver en dehors de cette zone.

Si vous ne définissez pas de limite ni de fenêtre d'affichage de la carte, l'API tentera de détecter l'emplacement de l'utilisateur en fonction de son adresse IP et pondérera les résultats en conséquence. Définissez une limite chaque fois que cela est possible. Sinon, les utilisateurs peuvent recevoir des prédictions différentes. De plus, pour améliorer les prédictions de manière générale, il est important de fournir une fenêtre d'affichage pertinente telle que celle que vous définissez en faisant un panoramique ou un zoom sur la carte, ou une fenêtre d'affichage définie par le développeur en fonction de la position de l'appareil et du rayon. Si aucun rayon n'est disponible, un rayon de 5 km est considéré comme une valeur par défaut raisonnable pour Place Autocomplete. Ne définissez pas une fenêtre d'affichage avec un rayon égal à zéro (un seul point), ni une fenêtre d'affichage qui n'inclut que quelques mètres (moins de 100 m) ou s'étend à tout le globe terrestre.

Restreindre la recherche de lieux par pays

Pour limiter la recherche de lieux à un ou plusieurs pays spécifiques, utilisez la includedRegionCodes propriété pour spécifier le ou les codes pays, comme indiqué dans l'extrait suivant (en supposant que vous avez déjà créé une instance nommée placeAutocomplete) :

placeAutocomplete.includedRegionCodes = ['us', 'au'];;

Restreindre la recherche de lieux aux limites de la carte

Pour limiter la recherche de lieux aux limites d'une carte, utilisez la locationRestriction propriété. L'extrait de code suivant montre comment ajouter un écouteur pour modifier les limites lorsqu'elles changent :

// Use the bounds_changed event to restrict results to the current map bounds.
google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
    placeAutocomplete.locationRestriction = innerMap.getBounds();
});

Pour supprimer le locationRestriction, définissez-le sur null.

Pondérer les résultats de recherche Place Search

Pour pondérer les résultats de recherche Place Search sur une zone circulaire, utilisez la locationBias propriété, comme indiqué ci-dessous :

placeAutocomplete.locationBias = {radius: 100, center: {lat: 40.749933, lng: -73.98633}};

Pour supprimer le locationBias, définissez-le sur null.

Limiter les résultats de recherche de lieux à certains types

Pour limiter les résultats de recherche de lieux à certains types de lieux, utilisez la includedPrimaryTypes propriété et indiquez un ou plusieurs types, comme indiqué ci-dessous :

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  includedPrimaryTypes: ['establishment'],
});

Pour obtenir la liste complète des types pris en charge, consultez les tableaux A et B des types de lieux.

Obtenir des informations sur un lieu

Pour obtenir des détails sur le lieu sélectionné, ajoutez un gmp-select écouteur au PlaceAutocompleteElement, comme indiqué dans l'exemple suivant :

TypeScript

// Add the gmp-select listener, and display the results.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({
        placePrediction,
    }: google.maps.places.PlacePredictionSelectEvent) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(),
            /* replacer */ null,
            /* space */ 2
        );
    }
);

JavaScript

// Add the gmp-select listener, and display the results.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(),
            /* replacer */ null,
            /* space */ 2
        );
    }
);

Voir l'exemple de code complet

Dans l'exemple précédent, l'écouteur d'événements reçoit un PlacePredictionSelectEvent et appelle placePrediction.toPlace() pour obtenir une instance de classe Place (Place reference). Appelez place.fetchFields() pour obtenir les champs de données Place Details nécessaires à votre application.

Dans l'exemple suivant, l'écouteur demande des informations de lieu et les affiche sur une carte.

TypeScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: [
                'displayName',
                'formattedAddress',
                'location',
                'viewport',
            ],
        });

        // If the place has a geometry, then present it on a map.
        if (place.viewport) {
            innerMap.fitBounds(place.viewport);
        } else {
            innerMap.setCenter(place.location!);
            innerMap.setZoom(17);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

        updateInfoWindow(content, place.location);
        marker.position = place.location;
    }
);

JavaScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: [
                'displayName',
                'formattedAddress',
                'location',
                'viewport',
            ],
        });

        // If the place has a geometry, then present it on a map.
        if (place.viewport) {
            innerMap.fitBounds(place.viewport);
        } else {
            innerMap.setCenter(place.location);
            innerMap.setZoom(17);
        }

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

        updateInfoWindow(content, place.location);
        marker.position = place.location;
    }
);

Voir l'exemple de code complet

Exemples de cartes

Cette section contient le code complet des exemples de cartes présentés sur cette page.

Élément de saisie semi-automatique

Cet exemple ajoute un widget de saisie semi-automatique à une page Web et affiche les résultats pour chaque lieu sélectionné.

TypeScript

async function init(): Promise<void> {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new PlaceAutocompleteElement();
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-select listener, and display the results.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({
            placePrediction,
        }: google.maps.places.PlacePredictionSelectEvent) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: ['displayName', 'formattedAddress', 'location'],
            });
            selectedPlaceTitle.textContent = 'Selected Place:';
            selectedPlaceInfo.textContent = JSON.stringify(
                place.toJSON(),
                /* replacer */ null,
                /* space */ 2
            );
        }
    );
}

void init();

JavaScript

async function init() {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new PlaceAutocompleteElement();
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-select listener, and display the results.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: ['displayName', 'formattedAddress', 'location'],
            });
            selectedPlaceTitle.textContent = 'Selected Place:';
            selectedPlaceInfo.textContent = JSON.stringify(
                place.toJSON(),
                /* replacer */ null,
                /* space */ 2
            );
        }
    );
}

void init();

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
    height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

p {
    font-family: Roboto, sans-serif;
    font-weight: bold;
}

HTML

<html>
    <head>
        <title>Place Autocomplete element</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <p style="font-family: roboto, sans-serif">Search for a place here:</p>
    </body>
</html>

Carte avec saisie semi-automatique

Cet exemple vous explique comment ajouter un widget Autocomplete à une carte Google.

TypeScript

const mapElement = document.querySelector('gmp-map')!;
const placeAutocomplete = document.querySelector('gmp-place-autocomplete')!;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
async function init(): Promise<void> {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds()!;
    });

    // Create the marker and infoWindow.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new InfoWindow();

    // Add the gmp-select listener, and display the results on the map.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: [
                    'displayName',
                    'formattedAddress',
                    'location',
                    'viewport',
                ],
            });

            // If the place has a geometry, then present it on a map.
            if (place.viewport) {
                innerMap.fitBounds(place.viewport);
            } else {
                innerMap.setCenter(place.location!);
                innerMap.setZoom(17);
            }

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            content.appendChild(addressText);

            updateInfoWindow(content, place.location);
            marker.position = place.location;
        }
    );
}

// Helper function to create an info window.
function updateInfoWindow(
    content: string | Element | Text | null | undefined,
    center: google.maps.LatLng | google.maps.LatLngLiteral | null | undefined
) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

void init();

JavaScript

const mapElement = document.querySelector('gmp-map');
const placeAutocomplete = document.querySelector('gmp-place-autocomplete');
let innerMap;
let marker;
let infoWindow;
async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });

    // Create the marker and infoWindow.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new InfoWindow();

    // Add the gmp-select listener, and display the results on the map.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: [
                    'displayName',
                    'formattedAddress',
                    'location',
                    'viewport',
                ],
            });

            // If the place has a geometry, then present it on a map.
            if (place.viewport) {
                innerMap.fitBounds(place.viewport);
            } else {
                innerMap.setCenter(place.location);
                innerMap.setZoom(17);
            }

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            content.appendChild(addressText);

            updateInfoWindow(content, place.location);
            marker.position = place.location;
        }
    );
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

void init();

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
gmp-map {
    height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}

.place-autocomplete-card {
    background-color: #fff;
    border-radius: 5px;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
    margin: 10px;
    padding: 5px;
    font-family: Roboto, sans-serif;
    font-size: small;
}

gmp-place-autocomplete {
    width: 300px;
}

#infowindow-content .title {
    font-weight: bold;
}

#map #infowindow-content {
    display: inline;
}

HTML

<html>
    <head>
        <title>Place Autocomplete map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
                key: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
            <div
                class="place-autocomplete-card"
                slot="control-inline-start-block-start">
                <gmp-place-autocomplete
                    placeholder="Search for a place..."></gmp-place-autocomplete>
            </div>
        </gmp-map>
    </body>
</html>

Optimisation de la saisie semi-automatique (nouvelle version)

Cette section décrit les bonnes pratiques pour vous aider à exploiter au mieux le service Autocomplete (New).

Voici quelques consignes générales :

  • Le moyen le plus rapide de développer une interface utilisateur fonctionnelle consiste à utiliser le widget Autocomplete (New) de l'API Maps JavaScript, le widget Autocomplete (New) du SDK Places pour Android, ou le widget Autocomplete (New) du SDK Places pour iOS.
  • Comprenez dès le départ les champs de données Autocomplete (New) 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 exceptions 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 Autocomplete (New) , utilisez des masques de champ dans les widgets Place Details (New) et Autocomplete (New) afin de ne renvoyer que les champs de donnéesAutocomplete (New) dont vous avez besoin.

Optimisation avancée des coûts

Envisagez d'implémenter Autocomplete (New) de manière programmatique pour accéder au tarif SKU : Autocomplete Request et demander des résultats d'API Geocoding pour le lieu sélectionné plutôt que pour Place Details (New). 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 et de la 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 (New).
  • Si les utilisateurs sélectionnent une prédiction de saisie semi-automatique toutes les quatre requêtes de prédiction Autocomplete (New) ou moins en moyenne, la tarification par requête peut être plus rentable que celle par session.
Pour obtenir de l'aide concernant la sélection de l'implémentation de la saisie semi-automatique (New) qui correspond à 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

Utilisez Autocomplete (New) basé sur des sessions avec Place Details (New)
Étant donné que votre application nécessite des informations Place Details (New) telles que le nom du lieu, l'état de l'établissement ou les horaires d'ouverture, votre implémentation d'Autocomplete (New) doit utiliser un jeton de session (de manière programmatique ou intégré aux JavaScript, Android, ou iOS) par session, auquel s'ajoutent les SKU Places en fonction des champs de données de lieu que vous demandez.1

Implémentation de widgets
La gestion de sessions est automatiquement intégrée aux JavaScript, Android, ou iOS. Cela inclut les requêtes Autocomplete (New) et la requête Place Details (New) pour la prédiction sélectionnée. Veillez à spécifier le fields paramètre pour vous assurer de ne demander que les champs de données Autocomplete (New) dont vous avez besoin.

Implémentation programmatique
Utilisez un jeton de session avec vos requêtes Autocomplete (New). 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 Autocomplete (New)
  2. Jeton de session utilisé dans la requête Autocomplete (New)
  3. Paramètre fields spécifiant les Autocomplete (New) champs de données 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 (New) pour votre application, en fonction de vos performances d'utilisation d'Autocomplete (New). L'efficacité de la saisie semi-automatique (New) 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 Autocomplete (New) dans votre application.

En moyenne, vos utilisateurs sélectionnent-ils une prédiction Autocomplete (New) en quatre requêtes ou moins ?

Oui

Implémentez Autocomplete (New) 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. Le coût de quatre requêtes Autocomplete plus un appel de l'API Geocoding pour la prédiction de lieu sélectionnée est inférieur au coût Autocomplete (New) 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 Autocomplete (New) basé sur des sessions avec Place Details (New)
É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 Autocomplete (New) dépasse le coût par session, votre implémentation d'Autocomplete (New) doit utiliser un jeton de session pour les requêtes Autocomplete (New) et la requête Place Details (New) associée par session. 1

Implémentation de widgets
La gestion de sessions est automatiquement intégrée aux JavaScript, Android, ou iOS. Cela inclut les requêtes Autocomplete (New) et la requête Place Details (New) pour la prédiction sélectionnée. Veillez à spécifier le paramètre fields pour vous assurer de ne demander que les champs dont vous avez besoin.

Implémentation programmatique
Utilisez un jeton de session avec vos requêtes Autocomplete (New). 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 Autocomplete (New)
  2. Jeton de session utilisé dans la requête Autocomplete (New)
  3. Paramètre fields spécifiant des champs tels que l'adresse et la géométrie

Envisagez de reporter les requêtes Autocomplete (New)
Vous pouvez appliquer des stratégies telles que le report d'une requête Autocomplete (New) 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 Autocomplete (New) 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 4 Autocomplete (New) par requête + 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 Autocomplete (New) à 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. Pour connaître les coûts, consultez les listes de tarifs de Google Maps Platform.

Bonnes pratiques en matière de performances

Les consignes suivantes décrivent les méthodes permettant d'optimiser les performances de la saisie semi-automatique (New) :

  • Ajoutez des restrictions locales applicables, une pondération géographique, et des préférences de langue (pour les implémentations programmatiques) à votre implémentation Autocomplete (New) . La préférence linguistique n'est pas obligatoire pour les widgets, car ils sélectionnent les préférences de langue dans le navigateur ou l'appareil mobile de l'utilisateur.
  • Si Autocomplete (New) 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 Autocomplete (New), 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 Place Details (New). Si les résultats ne sont attendus que dans une région spécifique, utilisez la pondération géographique.
    Voici d'autres scénarios dans lesquels il est préférable de revenir à l'API Geocoding :
    • Lorsque des utilisateurs saisissent des adresses de sous-établissement, par exemple des adresses d'unités ou d'appartements spécifiques dans un bâtiment. Par exemple, l'adresse tchèque "Stroupežnického 3191/17, Praha" génère une prédiction partielle dans Autocomplete (New).
    • 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ï.

Pondération géographique

Limitez les résultats à une zone spécifique en transmettant un paramètre location et un paramètre radius. Vous indiquez ainsi à Autocomplete (New) de privilégier les résultats situés à l'intérieur de la zone définie. Des résultats en dehors de la zone définie peuvent toutefois être affichés. Vous pouvez utiliser le paramètre includedRegionCodes pour filtrer les résultats et n'afficher que les lieux situés dans un pays spécifique.

Restriction géographique

Limitez les résultats à une zone spécifique en transmettant un paramètre locationRestriction.

Vous pouvez également limiter les résultats à la région définie par location et un paramètre radius en ajoutant le locationRestriction paramètre. Vous indiquez ainsi à Autocomplete (New) de ne renvoyer que les résultats situés dans cette région.