Widget do Place Autocomplete

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

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

Pré-requisitos

Para usar o Place Autocomplete, ative a API Places (nova) no 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 (Place reference) 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 de preenchimento automático 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 gmp-select listener. 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 novo google.maps.places.PlaceAutocompleteElement, e anexe-o à página, como mostrado no exemplo a seguir:

TypeScript

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

JavaScript

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

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 de preenchimento automático com um mapa do Google.

Para incluir esse widget em um mapa, primeiro peça 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 gmp-place-autocomplete elemento em um div e aninhe esse div em um gmp-map, como 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>

Para adicionar um widget de preenchimento automático a um mapa de forma programática, crie uma nova google.maps.places.PlaceAutocompleteElement instância, anexe o PlaceAutocompleteElement a uma div, e aplique o atributo slot à div, como 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 local 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 includedRegionCodes propriedade para definir os códigos dos países, como mostrado no snippet abaixo (isso pressupõe que você já criou 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 locationRestriction propriedade. 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 a uma área circular usando a locationBias propriedade, 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 conferir uma lista completa dos tipos aceitos, consulte as tabelas de tipos de lugares A e B.

Conferir detalhes sobre o lugar

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

TypeScript

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

JavaScript

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

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 (Place reference). Chame place.fetchFields() se quiser receber os campos de dados do Place Details necessários para seu aplicativo.

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

TypeScript

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

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

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

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

JavaScript

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

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

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

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

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.

TypeScript

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

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

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

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

void init();

JavaScript

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

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

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

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

void init();

CSS

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

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

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

HTML

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

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

Mapa de preenchimento automático

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

TypeScript

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

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

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

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

    infoWindow = new InfoWindow();

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

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

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

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

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

void init();

JavaScript

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

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

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

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

    infoWindow = new InfoWindow();

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

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

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

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

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

void init();

CSS

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

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

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

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

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

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

HTML

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

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

Otimização do preenchimento automático (novo)

Esta seção descreve as práticas recomendadas para você aproveitar ao máximo o serviço de preenchimento automático (novo).

Aqui estão algumas diretrizes gerais:

  • A maneira mais rápida de desenvolver uma interface do usuário funcional é usar o widget de preenchimento automático (novo) da API Maps JavaScript, o widget de preenchimento automático (novo) do SDK do Places para Android, ou o widget de preenchimento automático (novo) do SDK do Places para iOS.
  • Entenda 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 de preenchimento automático (novo) , use máscaras de campo nos widgets Place Details (novo) e preenchimento automático (novo) para retornar apenas os campos de dadosde preenchimento automático (novo) necessários.

Otimização avançada de custos

Faça a implementação programática do preenchimento automático (novo) para acessar o preço da SKU: solicitação de preenchimento automático e pedir resultados da API Geocoding sobre o lugar selecionado em vez do Place Details (novo). 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 (novo).
  • 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 preenchimento automático (novo) 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 preenchimento automático (novo) com base em sessões com o Place Details (novo).
Como seu app exige detalhes do lugar (novo), como nome, status comercial, ou horário de funcionamento, a implementação do preenchimento automático (novo) precisa usar um token de sessão (de forma programática ou integrada aos JavaScript, Android, ou iOS) por sessão, além de SKUs do Places relevantes, dependendo dos campos de dados de lugares que você solicita.1

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos JavaScript, Android, ou iOS widgets. Isso inclui as solicitações do preenchimento automático (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 de preenchimento automático (novo) necessários.

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

  1. O ID de lugar da resposta de preenchimento automático (novo)
  2. O token de sessão usado na solicitação de preenchimento automático (novo)
  3. O parâmetro fields que especifica os campos de dados de preenchimento automático (novo) necessários

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 preenchimento automático (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 de preenchimento automático (novo) no seu aplicativo.

As pessoas selecionam, em média, uma previsão de preenchimento automático (novo) em até quatro solicitações?

Sim

Implemente o preenchimento automático (novo) de forma programática sem tokens de sessão e chame 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 preenchimento automático além de uma chamada da API Geocoding sobre a previsão de lugar selecionada, é mais barato que o custo de preenchimento automático (novo) por sessão.1

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 preenchimento automático (novo) com base em sessões com o Place Details (novo).
Como a média de solicitações que você espera fazer antes de alguém selecionar uma previsão de preenchimento automático (novo) é maior que o custo do preço por sessão, a implementação do preenchimento automático (novo) precisa usar um token de sessão para as solicitações de preenchimento automático (novo) e a respectiva solicitação do Place Details (novo) por sessão. 1

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos JavaScript, Android, ou iOS widgets. Isso inclui as solicitações do preenchimento automático (novo) e do Place Details (novo) solicitação 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 de preenchimento automático (novo). Ao solicitar Place Details (novo) sobre a previsão selecionada, inclua os seguintes parâmetros:

  1. O ID do lugar da resposta de preenchimento automático (novo)
  2. O token de sessão usado na solicitação de preenchimento automático (novo)
  3. O parâmetro fields que especifica campos como endereço e geometria

Considere atrasar as solicitações de preenchimento automático (novo)
É possível adiar uma solicitação de preenchimento automático (novo) 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 ele digitar 7 caracteres e selecionar uma previsão em que você fez uma solicitação da API Geocoding, o custo total será de 4 preenchimentos automáticos (novo) por solicitação + Geocoding.1

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 preenchimento automático (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.


  1. Para conferir 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 preenchimento automático (novo):

  • Adicione restrições de país, direcionamento de local, e preferência de idioma (para implementações programáticas) à implementação do preenchimento automático (novo) . 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 preenchimento automático (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 do Place Details (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 digitam 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", em Nova York, ou "47-380 Kamehameha Hwy, Kaneohe", na ilha de Kauai, no Havaí.

Direcionamento de local

Direcione 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 na á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 especificado.

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âradiusmetro, adicionando o locationRestriction parâmetro. Isso instrui o preenchimento automático (novo) a retornar apenas resultados nessa região.