Esta página foi traduzida pela API Cloud Translation.

API Place Autocomplete Data

Desenvolvedores do Espaço Econômico Europeu (EEE)

A API Place Autocomplete Data permite buscar previsões de lugares de forma programática para criar experiências de preenchimento automático personalizadas com um grau de controle mais refinado do que é possível com o widget de preenchimento automático. Neste guia, você vai aprender a usar a API Place Autocomplete Data para fazer solicitações de preenchimento automático com base em consultas do usuário.

O exemplo a seguir mostra uma integração simplificada de preenchimento automático. Digite sua consulta de pesquisa, como "pizza" ou "poke", e clique para selecionar o resultado desejado.

Solicitações de Autocomplete

Uma solicitação de preenchimento automático usa uma string de entrada de consulta e retorna uma lista de previsões de lugares. Para fazer uma solicitação de preenchimento automático, chame fetchAutocompleteSuggestions() e transmita uma solicitação com as propriedades necessárias. A propriedade input contém a string a ser pesquisada. Em um aplicativo típico, esse valor seria atualizado à medida que o usuário digita uma consulta. A solicitação precisa incluir um sessionToken, que é usado para fins de faturamento.

O snippet a seguir mostra como criar um corpo de solicitação e adicionar um token de sessão. Em seguida, ele chama fetchAutocompleteSuggestions() para receber uma lista de PlacePredictions.

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

Restringir previsões de preenchimento automático

Por padrão, o Place Autocomplete apresenta todos os tipos de lugares, favorece previsões perto da localização do usuário e busca todos os campos de dados disponíveis para o lugar que a pessoa selecionou. Defina as opções do Place Autocomplete para mostrar previsões mais relevantes restringindo ou polarizando os resultados.

Quando você limita os resultados, o widget de preenchimento automático ignora todos os resultados que estão fora da área de restrição. Uma prática comum é restringir os resultados aos limites do mapa. A polarização de resultados faz com que o widget de preenchimento automático mostre resultados dentro da área especificada, mas algumas correspondências podem estar fora dessa região.

Use a propriedade origin para especificar o ponto de origem de onde calcular a distância geodésica até o destino. Se esse valor for omitido, a distância não será retornada.

Use a propriedade includedPrimaryTypes para especificar até cinco tipos de lugar. Se nenhum tipo for especificado, todos os tipos de lugares serão retornados.

Consulte a referência da API

Conferir detalhes sobre o lugar

Para retornar um objeto Place de um resultado de previsão de lugar, primeiro chame toPlace() e depois fetchFields() no objeto Place resultante. O ID da sessão da previsão de lugar é incluído automaticamente. Chamar fetchFields() encerra a sessão de preenchimento automático.

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

Tokens de sessão

Os tokens de sessão agrupam as fases de consulta e seleção de uma pesquisa de preenchimento automático do usuário em uma sessão discreta para fins de faturamento. A sessão começa quando o usuário começa a digitar. A sessão é concluída quando o usuário seleciona um lugar e uma chamada para Place Details é feita.

Para criar um novo token de sessão e adicioná-lo a uma solicitação, crie uma instância de AutocompleteSessionToken, defina a propriedade sessionToken da solicitação para usar os tokens, conforme mostrado no snippet a seguir:

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

Uma sessão é concluída quando fetchFields() é chamado. Depois de criar a instância Place, não é necessário transmitir o token de sessão para fetchFields(), porque isso é processado automaticamente.

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

Crie um token de sessão para a próxima sessão criando uma nova instância de AutocompleteSessionToken.

Recomendações de token de sessão:

Use tokens de sessão para todas as chamadas do Place Autocomplete.
Gere um novo token para cada sessão.
Transmita um token de sessão exclusivo para cada sessão nova. Se você usar o mesmo token para mais de uma sessão, cada solicitação vai ser faturada individualmente.

Você pode omitir o token de sessão do Autocomplete de uma solicitação. Se o token de sessão for omitido, cada solicitação será faturada separadamente, acionando a SKU Autocomplete – por solicitação. Se você reutilizar um token, a sessão será considerada inválida, e as solicitações serão cobradas como se nenhum token de sessão tivesse sido fornecido.

Exemplo

À medida que o usuário digita uma consulta, uma solicitação de preenchimento automático é chamada a cada poucas teclas (não por caractere), e uma lista de possíveis resultados é retornada. Quando o usuário faz uma seleção na lista de resultados, ela é contabilizada como uma solicitação, e todas as solicitações feitas durante a pesquisa são agrupadas e contadas como uma única solicitação. Se o usuário selecionar um lugar, a consulta de pesquisa estará disponível sem custos financeiros, e apenas a solicitação de dados do lugar será cobrada. Se o usuário não fizer uma seleção em alguns minutos após o início da sessão, apenas a consulta de pesquisa será cobrada.

Do ponto de vista de um app, o fluxo de eventos é assim:

Um usuário começa a digitar uma consulta para pesquisar "Paris, França".
Ao detectar a entrada do usuário, o app cria um novo token de sessão, "Token A".
À medida que o usuário digita, a API faz uma solicitação de preenchimento automático a cada poucos caracteres, mostrando uma nova lista de resultados possíveis para cada um:
"P"
"Par"
"Paris"
"Paris, Fr"
Quando o usuário faz uma seleção:
- Todas as solicitações resultantes da consulta são agrupadas e adicionadas à sessão representada pelo "Token A" como uma única solicitação.
- A seleção do usuário é contada como uma solicitação de Place Details e adicionada à sessão representada pelo "Token A".
A sessão é concluída, e o app descarta o "Token A".

Saiba como as sessões são faturadas

Exemplo de código completo

Esta seção contém exemplos completos que mostram como usar a API Place Autocomplete Data .

Previsões de preenchimento automático de lugar

O exemplo a seguir demonstra como chamar fetchAutocompleteSuggestions() para a entrada "Tadi", depois chamar toPlace() no primeiro resultado da previsão, seguido por uma chamada para fetchFields() para receber detalhes do lugar.

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

Testar amostra

JSFiddle.net

Preenchimento automático do Place Autocomplete com sessões

Este exemplo demonstra os seguintes conceitos:

Chamando fetchAutocompleteSuggestions() com base nas consultas do usuário e mostrando uma lista de lugares previstos em resposta.
Usar tokens de sessão para agrupar uma consulta do usuário com a solicitação final do Place Details.
Recuperar detalhes do lugar selecionado e mostrar um marcador.
Usar a inclusão de controles para aninhar elementos da interface no elemento 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

Testar amostra

JSFiddle.net

Otimização do Autocomplete (novo)

Esta seção descreve as práticas recomendadas para você aproveitar ao máximo o serviço Autocomplete (New).

Aqui estão algumas diretrizes gerais:

A maneira mais rápida de desenvolver uma interface do usuário funcional é usar o widget Preenchimento automático (novo) da API Maps JavaScript, o widget Preenchimento automático (novo) do SDK do Places para Android ou o widget Preenchimento automático (novo) do SDK do Places para iOS.
Entender os campos de dados essenciais do preenchimento automático (novo) desde o início.
Os campos de direcionamento de local e restrição de local são opcionais, mas podem afetar bastante a performance do preenchimento automático.
Use o tratamento de erros para garantir que o aplicativo faça uma degradação simples se a API retornar um erro.
Verifique se o app continua funcionando quando não há seleção e que oferece às pessoas uma maneira de continuar.

Práticas recomendadas de otimização de custos

Otimização básica de custos

Para otimizar o custo do uso do serviço Autocomplete (New), use máscaras de campo nos widgets Place Details (New) e Autocomplete (New) para retornar apenas os campos de dados do Autocomplete (New) necessários.

Otimização avançada de custos

Faça a implementação programática do Autocomplete (New) para acessar SKU: preços de solicitação do Autocomplete e peça resultados da API Geocoding sobre o lugar selecionado em vez do Place Details (New). O preço por solicitação combinado com a API Geocoding vai ser mais econômico que o preço por sessão se as duas condições a seguir forem atendidas:

Se você só precisa da latitude/longitude ou do endereço do local selecionado pela pessoa, a API Geocoding fornece essas informações por menos do que uma chamada do Place Details (New).
Se os usuários selecionarem uma previsão de preenchimento automático em média com quatro solicitações desse tipo, o preço por solicitação poderá ser mais econômico que o custo por sessão.

Se quiser ajuda para escolher a implementação do Autocomplete (New) de acordo com o que você precisa, selecione a guia correspondente à resposta à pergunta abaixo.

Seu aplicativo requer outras informações além do endereço e da latitude/longitude da previsão selecionada?

Sim, mais detalhes são necessários

Use o Autocomplete com base em sessões (novo) com o Place Details (novo).
Como seu aplicativo exige o Place Details (novo), como nome do lugar, status da empresa ou horário de funcionamento, sua implementação do Autocomplete (novo) precisa usar um token de sessão (de forma programática ou integrado aos widgets JavaScript, Android ou iOS) por sessão, além das SKUs do Places aplicáveis, dependendo dos campos de dados de lugar que você solicita.¹

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos widgets do JavaScript, Android, ou iOS. Isso inclui as solicitações do Autocomplete (novo) e do Place Details (novo) na previsão selecionada. Especifique o parâmetro fields para garantir que você está pedindo apenas os campos de dados do preenchimento automático (novo) necessários.

Implementação programática
Use um token de sessão com suas solicitações do Autocomplete (New). Ao solicitar Place Details (New) sobre a previsão selecionada, inclua os seguintes parâmetros:

O ID de lugar da resposta do Autocomplete (novo)
O token de sessão usado na solicitação do Autocomplete (New)
O parâmetro fields especificando os campos de dados do preenchimento automático (novo) que você precisa

Não, apenas o endereço e o local são necessários

A API Geocoding pode ser uma opção mais econômica que o Place Details (novo) para seu aplicativo, dependendo da performance do uso do Autocomplete (novo). A eficiência do preenchimento automático (novo) de cada aplicativo varia de acordo com o que as pessoas inserem, onde o aplicativo está sendo usado e se as práticas recomendadas de otimização de performance foram seguidas.

Para responder à pergunta a seguir, analise quantos caracteres a pessoa digita em média antes de selecionar uma previsão do Autocomplete (New) no seu aplicativo.

As pessoas selecionam, em média, uma previsão do Autocomplete (New) em até quatro solicitações?

Sim

Implementar o preenchimento automático (novo) de forma programática sem tokens de sessão e chamar a API Geocoding na previsão de lugar selecionada.
A API Geocoding oferece endereços e coordenadas de latitude/longitude. Fazer quatro solicitações de Autocomplete mais uma chamada da API Geocoding sobre a previsão de lugar selecionada custa menos do que o preço por sessão do Autocomplete (novo).¹

Convém usar as práticas recomendadas de performance para ajudar as pessoas a conseguir a previsão que querem usando ainda menos caracteres.

Não

Use o Autocomplete com base em sessões (novo) com o Place Details (novo).
Como o número médio de solicitações que você espera fazer antes que um usuário selecione uma previsão do Autocomplete (novo) excede o custo do preço por sessão, sua implementação do Autocomplete (novo) deve usar um token de sessão para as solicitações do Autocomplete (novo) e a solicitação associada do Place Details (novo) por sessão. ¹

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos widgets do JavaScript, Android ou iOS. Isso inclui as solicitações do Autocomplete (novo) e do Place Details (novo) na previsão selecionada. Especifique o parâmetro fields para garantir que você está pedindo apenas os campos necessários.

O ID de lugar da resposta do Autocomplete (novo)
O token de sessão usado na solicitação do Autocomplete (New)
O parâmetro fields que especifica campos como endereço e geometria

Considere atrasar as solicitações do Autocomplete (New)
É possível adiar uma solicitação do Autocomplete (New) até que a pessoa digite os três ou quatro primeiros caracteres, fazendo com que o aplicativo gere menos solicitações. Por exemplo, fazer solicitações de preenchimento automático (novo) para cada caractere depois que o usuário digita o terceiro caractere significa que, se o usuário digitar sete caracteres e selecionar uma previsão para a qual você faz uma solicitação da API Geocoding, o custo total será de quatro preenchimentos automáticos (novo) por solicitação + Geocoding.¹

Se for possível usar o atraso de solicitações para deixar sua solicitação programática média abaixo de quatro, siga as orientações para ter uma performance eficiente no Autocomplete (novo) com a API Geocoding. Atrasar solicitações pode ser percebido como latência pelo usuário, que talvez queira ver previsões a cada vez que pressionar uma nova tecla.

Convém usar as práticas recomendadas de performance para ajudar as pessoas a conseguir a previsão que querem usando ainda menos caracteres.

Para saber os custos, consulte as listas de preços da Plataforma Google Maps.

Práticas recomendadas de desempenho

As diretrizes a seguir descrevem como otimizar a performance do Autocomplete (novo):

Adicione restrições de país, direcionamento de local e preferência de idioma (para implementações programáticas) à implementação do Autocomplete (New). A preferência de idioma não é necessária com widgets porque eles usam o que está definido no navegador ou no dispositivo móvel do usuário.
Se o preenchimento automático (novo) estiver acompanhado por um mapa, é possível direcionar o local por janela de visualização do mapa.
Quando a pessoa não escolhe uma das previsões do Autocomplete (novo), geralmente porque nenhuma delas é o endereço que ela quer, você pode reutilizar a entrada original para tentar receber resultados mais relevantes:
- Se quiser que o usuário insira apenas informações de endereço, reutilize a entrada original dele em uma chamada para a API Geocoding.
- Se quiser que o usuário insira consultas para um lugar específico por nome ou endereço, use uma solicitação de detalhes do lugar (novo). Se os resultados forem esperados apenas em uma região específica, use o direcionamento de local.
Outros cenários em que é melhor voltar para a API Geocoding são:
- Usuários que inserem endereços de subunidades, como endereços de unidades ou apartamentos específicos em um prédio. Por exemplo, o endereço tcheco "Stroupežnického 3191/17, Praha" gera uma previsão parcial no preenchimento automático (novo).
- Usuários que digitam endereços com prefixos de trechos de via, como "23-30 29th St, Queens", na cidade de Nova York, ou "47-380 Kamehameha Hwy, Kaneohe", na ilha de Kauai, no Havaí.

Tendência de local

Influencie os resultados para uma área especificada transmitindo um parâmetro location e um parâmetro radius. Isso instrui o preenchimento automático (novo) a preferir mostrar resultados dentro da área definida. Os resultados fora da área definida ainda podem ser exibidos. Use o parâmetro components para filtrar os resultados e mostrar apenas os lugares em um país específico.

Aviso:se radius não for informado, o parâmetro location será ignorado.

Os resultados de estabelecimentos geralmente não têm uma classificação alta o suficiente para aparecer nos resultados quando a área de pesquisa é grande. Se você quiser que os estabelecimentos apareçam em resultados mistos de estabelecimento/código geográfico, especifique um raio menor. Como alternativa, use types=establishment para restringir os resultados apenas a estabelecimentos.

Restrição de local

Restrinja os resultados a uma área especificada transmitindo um parâmetro locationRestriction.

Você também pode restringir os resultados à região definida por location e um parâmetro radius, adicionando o parâmetro locationRestriction. Isso instrui o preenchimento automático (novo) a retornar apenas resultados nessa região.

API Place Autocomplete Data Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Solicitações de Autocomplete

Restringir previsões de preenchimento automático

Conferir detalhes sobre o lugar

Tokens de sessão

Recomendações de token de sessão:

Exemplo

Exemplo de código completo

Previsões de preenchimento automático de lugar

TypeScript

JavaScript

CSS

HTML

Testar amostra

Preenchimento automático do Place Autocomplete com sessões

TypeScript

JavaScript

CSS

HTML

Testar amostra

Otimização do Autocomplete (novo)

Práticas recomendadas de otimização de custos

Otimização básica de custos

Otimização avançada de custos

Sim, mais detalhes são necessários

Não, apenas o endereço e o local são necessários

Sim

Não

Práticas recomendadas de desempenho

Tendência de local

Restrição de local

API Place Autocomplete Data