Cette page a été traduite par l'API Cloud Translation.

API Place Autocomplete Data

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

L'API Place Autocomplete Data vous permet d'extraire des prédictions de lieux de manière programmatique, afin de créer des expériences de saisie semi-automatique personnalisées avec un degré de contrôle plus précis que celui possible avec le widget de saisie semi-automatique. Dans ce guide, vous allez apprendre à utiliser l'API Place Autocomplete Data pour envoyer des requêtes d'autocomplete en fonction des requêtes des utilisateurs.

L'exemple suivant montre une intégration de saisie semi-automatique simplifiée. Saisissez votre requête, par exemple "pizza" ou "poke", puis cliquez sur le résultat souhaité.

Requêtes Autocomplete

Une requête Autocomplete prend une chaîne de requête en entrée et renvoie une liste de prédictions de lieux. Pour envoyer une requête d'autocomplete, appelez fetchAutocompleteSuggestions() et transmettez une requête avec les propriétés requises. La propriété input contient la chaîne à rechercher. Dans une application classique, cette valeur est mise à jour à mesure que l'utilisateur saisit une requête. La requête doit inclure un sessionToken, qui est utilisé à des fins de facturation.

L'extrait suivant montre comment créer un corps de requête et ajouter un jeton de session, puis appeler fetchAutocompleteSuggestions() pour obtenir une liste de PlacePrediction.

// Add an initial request body.
let request = {
    input: 'Tadi',
    locationRestriction: {
        west: -122.44,
        north: 37.8,
        east: -122.39,
        south: 37.78,
    },
    origin: { lat: 37.7893, lng: -122.4039 },
    includedPrimaryTypes: ['restaurant'],
    language: 'en-US',
    region: 'us',
};
// Create a session token.
const token = new AutocompleteSessionToken();
// Add the token to the request.
// @ts-ignore
request.sessionToken = token;index.js

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

Utilisez la propriété origin pour spécifier le point d'origine à partir duquel calculer la distance géodésique jusqu'à la destination. Si cette valeur est omise, la distance n'est pas renvoyée.

Utilisez la propriété includedPrimaryTypes pour spécifier jusqu'à cinq types de lieux. Si aucun type n'est spécifié, les lieux de tous les types seront renvoyés.

Consulter la documentation de référence de l'API

Obtenir des informations sur un lieu

Pour renvoyer un objet Place à partir d'un résultat de prédiction de lieu, appelez d'abord toPlace(), puis fetchFields() sur l'objet Place obtenu (l'ID de session de la prédiction de lieu est automatiquement inclus). L'appel de fetchFields() met fin à la session d'autocomplete.

let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
await place.fetchFields({
    fields: ['displayName', 'formattedAddress'],
});
const placeInfo = document.getElementById('prediction');
placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;index.js

Jetons de session

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 du texte. La session se termine lorsque l'utilisateur sélectionne un lieu et qu'un appel à Place Details est effectué.

Pour créer un jeton de session et l'ajouter à une requête, créez une instance de AutocompleteSessionToken, puis définissez la propriété sessionToken de la requête pour utiliser les jetons, comme indiqué dans l'extrait de code suivant :

// Create a session token.
const token = new AutocompleteSessionToken();
// Add the token to the request.
// @ts-ignore
request.sessionToken = token;index.js

Une session se termine lorsque fetchFields() est appelé. Après avoir créé l'instance Place, vous n'avez pas besoin de transmettre le jeton de session à fetchFields(), car cela est géré automatiquement.

await place.fetchFields({
    fields: ['displayName', 'formattedAddress'],
});index.js

Créez un jeton de session pour la prochaine session en créant une instance de AutocompleteSessionToken.

Recommandations concernant les jetons de session :

Utilisez des jetons de session pour tous les appels Place Autocomplete.
Générez un nouveau jeton pour chaque session.
Transmettez 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.

Vous pouvez éventuellement omettre le jeton de session Autocomplete d'une requête. Si le jeton de session est omis, chaque requête est facturée séparément, ce qui déclenche le SKU Autocomplete – Per Request. Si vous en réutilisez un, la session est considérée comme non valide, et les requêtes sont facturées comme si aucun jeton n'avait été fourni.

Exemple

À mesure que l'utilisateur saisit une requête, une requête de saisie semi-automatique est appelée toutes les quelques frappes (et non par caractère), et une liste de résultats possibles est renvoyée. Lorsque l'utilisateur effectue une sélection dans la liste des résultats, cette sélection est considérée comme une demande. Toutes les demandes effectuées lors de la recherche sont regroupées et comptabilisées comme une seule demande. Si l'utilisateur sélectionne un lieu, la requête de recherche est disponible sans frais, et seuls les frais de demande de données sur le lieu sont facturés. Si l'utilisateur ne fait pas de sélection dans les minutes qui suivent le début de la session, seule la requête de recherche est facturée.

Du point de vue d'une application, le flux d'événements se déroule comme suit :

Un utilisateur commence à saisir une requête pour rechercher "Paris, France".
Lorsqu'une saisie utilisateur est détectée, l'application crée un jeton de session, "Jeton A".
À mesure que l'utilisateur saisit du texte, l'API envoie une requête de saisie semi-automatique tous les quelques caractères, en affichant une nouvelle liste de résultats potentiels pour chacun :
"P"
"Par"
"Paris,"
"Paris, Fr"
Lorsque l'utilisateur effectue une sélection :
- Toutes les requêtes résultant de la requête sont regroupées et ajoutées à la session représentée par "Jeton A", en tant que requête unique.
- La sélection de l'utilisateur est comptabilisée comme une demande Place Details et ajoutée à la session représentée par le jeton A.
La session se termine et l'application supprime le jeton A.

En savoir plus sur la facturation des sessions

Exemple de code complet

Cette section contient des exemples complets montrant comment utiliser l'API Place Autocomplete Data .

Prédictions de saisie semi-automatique de lieux

L'exemple suivant montre comment appeler fetchAutocompleteSuggestions() pour l'entrée "Tadi", puis comment appeler toPlace() sur le premier résultat de prédiction, suivi d'un appel à fetchFields() pour obtenir des informations sur le lieu.

TypeScript

async function init() {
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } =
        (await google.maps.importLibrary(
            'places'
        )) as google.maps.PlacesLibrary;

    // Add an initial request body.
    let request = {
        input: 'Tadi',
        locationRestriction: {
            west: -122.44,
            north: 37.8,
            east: -122.39,
            south: 37.78,
        },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ['restaurant'],
        language: 'en-US',
        region: 'us',
    };

    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    // @ts-ignore
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    const title = document.getElementById('title') as HTMLElement;
    title.appendChild(
        document.createTextNode(
            'Query predictions for "' + request.input + '":'
        )
    );

    const resultsElement = document.getElementById('results') as HTMLElement;

    for (let suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a new list element.
        const listItem = document.createElement('li');

        listItem.appendChild(
            document.createTextNode(placePrediction!.text.toString())
        );
        resultsElement.appendChild(listItem);
    }

    let place = suggestions[0].placePrediction!.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });

    const placeInfo = document.getElementById('prediction') as HTMLElement;
    placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
}

init();index.ts

JavaScript

async function init() {
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } = (await google.maps.importLibrary('places'));
    // Add an initial request body.
    let request = {
        input: 'Tadi',
        locationRestriction: {
            west: -122.44,
            north: 37.8,
            east: -122.39,
            south: 37.78,
        },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ['restaurant'],
        language: 'en-US',
        region: 'us',
    };
    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    // @ts-ignore
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
    const title = document.getElementById('title');
    title.appendChild(document.createTextNode('Query predictions for "' + request.input + '":'));
    const resultsElement = document.getElementById('results');
    for (let suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;
        // Create a new list element.
        const listItem = document.createElement('li');
        listItem.appendChild(document.createTextNode(placePrediction.text.toString()));
        resultsElement.appendChild(listItem);
    }
    let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });
    const placeInfo = document.getElementById('prediction');
    placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
}
init();index.js

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;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete Data API Predictions</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- prettier-ignore -->
        <script>(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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <div id="title"></div>
        <ul id="results"></ul>
        <p><span id="prediction"></span></p>
        <img
            class="powered-by-google"
            src="./powered_by_google_on_white.png"
            alt="Powered by Google" />
    </body>
</html>index.html

Essayer l'exemple

JSFiddle.net

Saisie semi-automatique Place Autocomplete avec sessions

Cet exemple illustre les concepts suivants :

Appel de fetchAutocompleteSuggestions() en fonction des requêtes des utilisateurs et affichage d'une liste de lieux prédits en réponse.
Utilisation de jetons de session pour regrouper une requête utilisateur avec la requête Place Details finale.
Récupérer les détails du lieu sélectionné et afficher un repère.
Utiliser l'emplacement de contrôle pour imbriquer des éléments d'UI dans l'élément gmp-map.

TypeScript

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let titleElement = document.querySelector('.title') as HTMLElement;
let resultsContainerElement = document.querySelector('.results') as HTMLElement;
let inputElement = document.querySelector('input') as HTMLInputElement;
let tokenStatusElement = document.querySelector('.token-status') as HTMLElement;
let newestRequestId = 0;
let tokenCount = 0;

// Create an initial request body.
const request: google.maps.places.AutocompleteRequest = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};

async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Update request center and bounds when the map bounds change.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });

    inputElement.addEventListener('input', makeAutocompleteRequest);
}

async function makeAutocompleteRequest(inputEvent) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;

    const { AutocompleteSuggestion } = (await google.maps.importLibrary(
        'places'
    )) as google.maps.PlacesLibrary;

    if (!inputEvent.target?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = (inputEvent.target as HTMLInputElement).value;

    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId) return;

    titleElement.innerText = `Place predictions for "${request.input}"`;

    // Clear the list first.
    resultsContainerElement.replaceChildren();

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        if (!placePrediction) {
            continue;
        }

        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            onPlaceSelected(placePrediction.toPlace());
        });
        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');

        // Create a new list item element.
        const li = document.createElement('li');
        li.appendChild(placeButton);
        resultsContainerElement.appendChild(li);
    }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place: google.maps.places.Place) {
    const { AdvancedMarkerElement } = (await google.maps.importLibrary(
        'marker'
    )) as google.maps.MarkerLibrary;

    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });

    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';

    await refreshToken();

    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }

    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });

    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}

// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } = (await google.maps.importLibrary(
        'places'
    )) as google.maps.PlacesLibrary;

    // Increment the token counter.
    tokenCount++;

    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}

init();index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;
let marker;
let titleElement = document.querySelector('.title');
let resultsContainerElement = document.querySelector('.results');
let inputElement = document.querySelector('input');
let tokenStatusElement = document.querySelector('.token-status');
let newestRequestId = 0;
let tokenCount = 0;
// Create an initial request body.
const request = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};
async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Update request center and bounds when the map bounds change.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });
    inputElement.addEventListener('input', makeAutocompleteRequest);
}
async function makeAutocompleteRequest(inputEvent) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;
    const { AutocompleteSuggestion } = (await google.maps.importLibrary('places'));
    if (!inputEvent.target?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }
    // Add the latest char sequence to the request.
    request.input = inputEvent.target.value;
    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId)
        return;
    titleElement.innerText = `Place predictions for "${request.input}"`;
    // Clear the list first.
    resultsContainerElement.replaceChildren();
    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;
        if (!placePrediction) {
            continue;
        }
        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            onPlaceSelected(placePrediction.toPlace());
        });
        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');
        // Create a new list item element.
        const li = document.createElement('li');
        li.appendChild(placeButton);
        resultsContainerElement.appendChild(li);
    }
}
// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    const { AdvancedMarkerElement } = (await google.maps.importLibrary('marker'));
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';
    await refreshToken();
    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }
    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });
    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}
// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } = (await google.maps.importLibrary('places'));
    // Increment the token counter.
    tokenCount++;
    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}
init();index.js

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-button {
    height: 3rem;
    width: 100%;
    background-color: transparent;
    text-align: left;
    border: none;
    cursor: pointer;
}

.place-button:focus-visible {
    outline: 2px solid #0056b3;
    border-radius: 2px;
}

.input {
    width: 300px;
    font-size: small;
    margin-bottom: 1rem;
}

/* Styles for the floating panel */
.controls {
    background-color: #fff;
    border-radius: 8px;
    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
    font-family: sans-serif;
    font-size: small;
    margin: 12px;
    padding: 1rem;
}

.title {
    font-weight: bold;
    margin-top: 1rem;
    margin-bottom: 0.5rem;
}

.results {
    list-style-type: none;
    margin: 0;
    padding: 0;
}

.results li:not(:last-child) {
    border-bottom: 1px solid #ddd;
}

.results li:hover {
    background-color: #eee;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete Data API Session</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- prettier-ignore -->
        <script>(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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <gmp-map center="37.7893, -122.4039" zoom="12" map-id="DEMO_MAP_ID">
            <div class="controls" slot="control-inline-start-block-start">
                <input
                    type="text"
                    class="input"
                    placeholder="Search for a place..."
                    autocomplete="off" /><!-- Turn off the input's own autocomplete (not supported by all browsers).-->
                <div class="token-status"></div>
                <div class="title"></div>
                <ol class="results"></ol>
            </div>
        </gmp-map>
    </body>
</html>index.html

Essayer l'exemple

JSFiddle.net

Optimisation d'Autocomplete (nouveau)

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

Voici quelques consignes générales :

La méthode la plus rapide pour développer une interface utilisateur fonctionnelle consiste à utiliser le widget de saisie semi-automatique (nouveau) de l'API Maps JavaScript, le widget de saisie semi-automatique (nouveau) du SDK Places pour Android ou le widget de saisie semi-automatique (nouveau) du SDK Places pour iOS.
Développez dès le départ vos connaissances des champs de données Autocomplete (nouveau) 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 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ées Autocomplete (New) dont vous avez besoin.

Optimisation avancée des coûts

Envisagez d'implémenter Autocomplete (nouveau) de manière programmatique pour accéder au tarif par requête Autocomplete et demander des résultats d'API Geocoding pour le lieu sélectionné plutôt que pour Place Details (nouveau). 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 (nouveau).
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 l'implémentation d'Autocomplete (nouveau) 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

Utilisez Autocomplete (nouveau) basé sur des sessions avec Place Details (nouveau).
Étant donné que votre application nécessite des détails sur les lieux (nouveaux), tels que le nom du lieu, l'état de l'établissement ou les horaires d'ouverture, votre implémentation d'Autocomplete (nouveau) doit utiliser un jeton de session (de manière programmatique ou intégré aux widgets JavaScript, Android ou iOS) par session, ainsi que les SKU Places applicables, en fonction des 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 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 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 (nouveau) concernant la prédiction sélectionnée, incluez les paramètres suivants :

ID de lieu figurant dans la réponse Autocomplete (New)
Jeton de session utilisé dans la requête Autocomplete (New)
Le paramètre fields spécifiant les champs de données Autocomplete (New) 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 (nouveau) pour votre application, en fonction de vos performances d'utilisation d'Autocomplete (nouveau). L'efficacité de la saisie semi-automatique (nouvelle version) 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 (nouveau) 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 par session d'Autocomplete (nouveau)¹.

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 (nouveau) basé sur des sessions avec Place Details (nouveau).
Étant donné que le nombre moyen de requêtes que vous prévoyez d'envoyer avant qu'un utilisateur ne sélectionne une prédiction Autocomplete (New) dépasse le coût de la tarification 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. ¹

ID de lieu figurant dans la réponse Autocomplete (New)
Jeton de session utilisé dans la requête Autocomplete (New)
Paramètre fields spécifiant les champs, comme 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 envoyez des requêtes Autocomplete (New) pour chaque caractère après le troisième caractère saisi par l'utilisateur, cela signifie que si l'utilisateur saisit sept caractères, puis sélectionne une prédiction pour laquelle vous envoyez une requête API Geocoding, le coût total correspondra à quatre requêtes Autocomplete (New) par requête plus une requête Geocoding.¹

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 (nouveau) à 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.

Pour connaître les coûts, consultez les listes de prix de Google Maps Platform.

Bonnes pratiques en matière de performances

Les consignes suivantes décrivent les méthodes permettant d'optimiser les performances d'Autocomplete (nouveau) :

Ajoutez des restrictions locales, une pondération géographique et des préférences linguistiques (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 cette option dans le navigateur ou l'appareil mobile de l'utilisateur.
Si la saisie semi-automatique (nouvelle version) est accompagnée 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 (nouvelle), 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 :
- Les utilisateurs saisissent des adresses de sous-lieux, comme 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ï.

Biais de localisation

Limitez les résultats à une zone spécifique en transmettant les paramètres location et radius. Cela indique à la saisie semi-automatique (nouvelle version) de privilégier les résultats dans 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 components pour filtrer les résultats et n'afficher que les lieux situés dans un pays spécifique.

Avertissement : Si radius n'est pas fourni, le paramètre location est ignoré.

Les résultats d'établissements ne sont généralement pas assez bien classés pour s'afficher dans les résultats lorsque la zone de recherche est étendue. Si vous souhaitez que des établissements apparaissent dans les résultats mixtes (établissements/codes géographiques), vous pouvez spécifier un rayon plus petit. Vous pouvez également utiliser types=establishment pour limiter les résultats aux établissements.

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 les paramètres location et radius en ajoutant le paramètre locationRestriction. Cela indique à Autocomplete (New) de ne renvoyer que les résultats dans cette région.

API Place Autocomplete Data Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Requêtes Autocomplete

Limiter les prédictions de saisie semi-automatique

Obtenir des informations sur un lieu

Jetons de session

Recommandations concernant les jetons de session :

Exemple

Exemple de code complet

Prédictions de saisie semi-automatique de lieux

TypeScript

JavaScript

CSS

HTML

Essayer l'exemple

Saisie semi-automatique Place Autocomplete avec sessions

TypeScript

JavaScript

CSS

HTML

Essayer l'exemple

Optimisation d'Autocomplete (nouveau)

Bonnes pratiques liées à l'optimisation des coûts

Optimisation de base des coûts

Optimisation avancée des coûts

Oui, j'ai besoin de plus d'informations

Non, seuls les adresses et les lieux sont nécessaires

Oui

Non

Bonnes pratiques en matière de performances

Biais de localisation

Restriction géographique

API Place Autocomplete Data