Widget do Place Autocomplete

O widget do Place Autocomplete cria um campo de entrada de texto, oferece previsões de lugares em uma lista de seleção na interface e retorna Place Details em resposta à seleção do usuário. Use o widget do Place Autocomplete para incorporar uma interface do usuário de preenchimento automático completa e independente na sua página da Web. Para ver a referência completa da API, consulte PlaceAutocompleteElement.

Pré-requisitos

Para usar o Place Autocomplete, ative a API Places (nova) no seu projeto do Google Cloud. Consulte o artigo Começar para mais detalhes.

O que há de novo

O Place Autocomplete foi aprimorado das seguintes maneiras:

• A interface do widget de preenchimento automático agora é compatível com a localização regional (incluindo idiomas escritos da direita para a esquerda) para o marcador de posição de entrada de texto, o logo da lista de previsões e as estimativas de lugares.
• A acessibilidade foi otimizada, incluindo compatibilidade com leitores de tela e interação com o teclado.
• O widget de preenchimento automático agora retorna a nova classe Place (referência de Place) para simplificar o gerenciamento do objeto retornado.
• O suporte a dispositivos móveis e telas pequenas foi aprimorado.
• Fizemos melhorias na performance e na aparência.

Adicionar um widget de preenchimento automático

O widget Autocomplete cria um campo de entrada de texto, oferece previsões de lugares em uma lista de seleção na interface e retorna Place Details em resposta a um clique da pessoa usando o listener gmp-select. Nesta seção, mostramos como adicionar um widget de preenchimento automático a uma página da Web ou um mapa do Google.

Adicionar um widget de preenchimento automático a uma página da Web

Para incluir esse widget em uma página da Web, crie um elemento google.maps.places.PlaceAutocompleteElement e anexe-o à página, como mostrado no exemplo a seguir:

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

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

Confira o exemplo completo de código.

Adicionar um widget de preenchimento automático a um mapa

Se o endereço de faturamento estiver fora do Espaço Econômico Europeu (EEE), você também poderá usar o widget do Autocomplete com um mapa do Google.

Para adicionar um widget de preenchimento automático a um mapa, primeiro solicite as bibliotecas necessárias, como mostrado aqui:

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

Em seguida, no HTML, aninhe um novo elemento gmp-place-autocomplete em um div e aninhe esse div em um gmp-map, conforme mostrado no exemplo a seguir:

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

Para adicionar um widget de preenchimento automático a um mapa de forma programática, crie uma nova instância de google.maps.places.PlaceAutocompleteElement, anexe PlaceAutocompleteElement a um div e aplique o atributo slot ao div, conforme mostrado no exemplo a seguir:

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

Confira o exemplo completo de código.

Adicionar texto de preenchimento

Use a propriedade placeholder para adicionar texto de preenchimento. O exemplo a seguir mostra como definir o texto de preenchimento em HTML:

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

Também é possível definir o texto de preenchimento de forma programática:

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

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

Se nenhuma janela de visualização de mapa ou limite é fornecido, a API tenta detectar a localização da pessoa pelo endereço IP e prioriza os resultados para lá. Defina limites sempre que possível. Caso contrário, cada usuário pode receber uma previsão diferente. Além disso, para melhorar as previsões, é importante oferecer uma janela de visualização adequada (como aquelas que você define movimentando ou aumentando o zoom do mapa) ou definida pelo desenvolvedor com base no raio e no local do dispositivo. Quando um raio não está disponível, 5 km é considerado um padrão adequado para o Place Autocomplete. Não defina uma janela de visualização com raio zero (um único ponto), que tenha apenas alguns metros de extensão (menos de 100 m) ou que abranja todo o globo.

Restringir a pesquisa de lugares por país

Se quiser restringir a pesquisa de lugares a um ou mais países específicos, use a propriedade includedRegionCodes para definir os códigos dos países, como mostrado no snippet abaixo (presumindo que você já tenha criado uma instância chamada placeAutocomplete):

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

Restringir a pesquisa de lugares aos limites do mapa

Para restringir a Place Search aos limites de um mapa, use a propriedade locationRestriction. O snippet a seguir mostra como adicionar um listener para atualizar os limites quando eles mudarem:

// 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();
});

Para remover o locationRestriction, defina-o como null.

Polarizar os resultados da pesquisa de lugares

Polarize os resultados da pesquisa de lugares para uma área circular usando a propriedade locationBias, como mostrado aqui:

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

Para remover o locationBias, defina-o como null.

Restringir os resultados da pesquisa de lugares a determinados tipos

Restrinja os resultados da pesquisa de Place Search a determinados tipos de lugares usando a propriedade includedPrimaryTypes e especificando um ou mais tipos, como mostrado aqui:

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

Para uma lista completa de tipos compatíveis, consulte as tabelas A e B de tipos de lugar.

Conferir detalhes sobre o lugar

Para consultar detalhes sobre o lugar selecionado, adicione um listener gmp-select a PlaceAutocompleteElement, como mostrado no exemplo abaixo:

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

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

Confira o exemplo completo de código.

No exemplo anterior, o listener de eventos recebe um PlacePredictionSelectEvent e chama placePrediction.toPlace() para receber uma instância da classe Place (referência de Place). Chame place.fetchFields() se quiser receber os campos de dados do Place Details necessários para seu aplicativo.

O listener do exemplo a seguir solicita os campos displayName, formattedAddress, location e viewport em place.fetchFields() e usa place.viewport com fitBounds() para mostrar o lugar selecionado em um mapa.

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

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

Confira o exemplo completo de código.

Exemplos de mapas

Esta seção inclui o código completo dos exemplos de mapas apresentados na página.

Preencher um elemento automaticamente

Neste exemplo, adicionamos um widget de preenchimento automático a uma página da Web e mostramos os resultados de cada lugar selecionado.

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

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

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

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

Preencher um mapa automaticamente

Neste exemplo, mostramos como adicionar um widget de preenchimento automático a um mapa do Google.

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

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

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

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

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 do Autocomplete (novo) da API Maps JavaScript, o widget do Autocomplete (novo) do SDK do Places para Android ou o widget do Autocomplete (novo) do SDK do Places para iOS.
• Entender os campos de dados essenciais do Autocomplete (New) 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 (novo), use máscaras de campo nos widgets Place Details (novo) e Autocomplete (novo) para retornar apenas os campos de dados do Autocomplete (novo) necessários.

Otimização avançada de custos

Faça a implementação programática do Autocomplete (New) para acessar os preços da SKU: Autocomplete Request e pedir 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 e 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 (novo), o preço por solicitação poderá ser mais econômico que o custo por sessão.

A API Geocoding pode ser uma opção mais econômica que o Place Details (novo) para seu aplicativo, dependendo da performance do Autocomplete (novo). A eficiência do Autocomplete (New) 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 encontrar o número médio de solicitações para a tabela, analise quantos caracteres um usuário digita em média antes de selecionar uma previsão do Autocomplete (novo) no seu aplicativo.

Autocomplete (novo) com base em sessões com Place Details (novo)

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

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 Autocomplete (New) 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:

1. O ID de lugar da resposta do Autocomplete (novo)
2. O token de sessão usado na solicitação do Autocomplete (novo)
3. O parâmetro fields especificando os campos de dados do Autocomplete (New) necessários.

Preenchimento automático (novo) por solicitação com a API Geocoding

Implementar o Autocomplete (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 do Autocomplete, além de uma chamada da API Geocoding sobre a previsão de lugar selecionada, é mais barato do que o custo 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.

Autocomplete (novo) com base em sessões para aplicativos que usam apenas endereços

Use o Autocomplete (novo) com base em sessões 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.

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:

1. O ID de lugar da resposta do Autocomplete (novo)
2. O token de sessão usado na solicitação do Autocomplete (novo)
3. 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, se você fizer solicitações do Autocomplete (New) para cada caractere depois que o usuário digitar o terceiro caractere, e ele digitar sete caracteres e selecionar uma previsão para a qual você faz uma solicitação da API Geocoding, o custo total será de 4 solicitações do Autocomplete (New) + 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 (New) 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.

Práticas recomendadas de desempenho

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

• 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 Autocomplete (New) 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 (New), 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 do Place Details (New). 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 subpremissas, 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 Autocomplete (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í.

Polarização de local

Direcione os resultados para uma área específica transmitindo um parâmetro location e um parâmetro radius. Isso instrui o Autocomplete (New) a priorizar os resultados dentro da área definida. Os resultados fora da área definida ainda podem ser exibidos. Use o parâmetro includedRegionCodes para filtrar os resultados e mostrar apenas os lugares em um país específico.

Restrição de local

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

Também é possível restringir os resultados à região definida por location e um parâmetro radius adicionando o parâmetro locationRestriction. Isso instrui o Autocomplete (New) a retornar apenas resultados dentro dessa região.