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 do Place Autocomplete para incorporar uma interface do usuário de preenchimento automático completa e independente na sua página da Web.

Pré-requisitos

Para usar o recurso de preenchimento automático de lugar, 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 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 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 o 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:

TypeScript

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

JavaScript

// Request needed libraries.
(await google.maps.importLibrary('places'));
// Create the input HTML element, and append it.
const placeAutocomplete = new google.maps.places.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 de preenchimento automático com um mapa do Google.

Para incluir esse widget em um mapa, crie uma instância de google.maps.places.PlaceAutocompleteElement, anexe PlaceAutocompleteElement a uma div e envie-o para o mapa como um controle personalizado, conforme o exemplo a seguir:

TypeScript

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

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

JavaScript

// Get the inner map.
innerMap = mapElement.innerMap;
innerMap.setOptions({
    mapTypeControl: false,
});
// 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();
});
index.js

Confira o exemplo completo de código.

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 você não fornecer limites ou uma janela de visualização de mapa, a API tentará detectar a localização do usuário pelo endereço IP e priorizará os resultados para esse local. 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:

const pac = new google.maps.places.PlaceAutocompleteElement({
  includedRegionCodes: ['us', 'au'],
});

Restringir a pesquisa de lugares aos limites do mapa

Se quiser fazer isso, use a propriedade locationRestrictions para adicionar os limites, como mostrado no snippet abaixo:

const pac = new google.maps.places.PlaceAutocompleteElement({
  locationRestriction: map.getBounds(),
});

Ao fazer a restrição, inclua um listener para atualizar os limites quando eles mudarem:

map.addListener('bounds_changed', () => {
  autocomplete.locationRestriction = map.getBounds();
});

Para remover locationRestriction, defina-o como null.

Polarizar os resultados da pesquisa de lugares

Polarize os resultados a uma área circular usando a propriedade locationBias e transmitindo um raio, como mostrado aqui:

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  locationBias: {radius: 100, center: {lat: 50.064192, lng: -130.605469}},
});

Para remover locationBias, defina-o como null.

Restringir os resultados da pesquisa de lugares a determinados tipos

Para fazer isso, use a propriedade includedPrimaryTypes e especifique 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 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:

TypeScript

// Add the gmp-placeselect listener, and display the results.
//prettier-ignore
//@ts-ignore
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.ts

JavaScript

// Add the gmp-placeselect listener, and display the results.
//prettier-ignore
//@ts-ignore
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 retorna um objeto da classe 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 pede informações sobre o lugar e mostra tudo em um mapa.

TypeScript

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

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

    let content = document.createElement('div');
    let nameText = document.createElement('span');
    nameText.textContent = place.displayName;
    content.appendChild(nameText);
    content.appendChild(document.createElement('br'));
    let addressText = document.createElement('span');
    addressText.textContent = place.formattedAddress;
    content.appendChild(addressText);

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

JavaScript

// Add the gmp-placeselect listener, and display the results on the map.
//prettier-ignore
//@ts-ignore
placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
    const place = placePrediction.toPlace();
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    // 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);
    }
    let content = document.createElement('div');
    let nameText = document.createElement('span');
    nameText.textContent = place.displayName;
    content.appendChild(nameText);
    content.appendChild(document.createElement('br'));
    let addressText = document.createElement('span');
    addressText.textContent = place.formattedAddress;
    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.

TypeScript

async function initMap(): Promise<void> {
    // Request needed libraries.
    (await google.maps.importLibrary('places')) as google.maps.PlacesLibrary;
    // Create the input HTML element, and append it.
    const placeAutocomplete = new google.maps.places.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-placeselect listener, and display the results.
    //prettier-ignore
    //@ts-ignore
    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);
    });
}

initMap();
index.ts

JavaScript

async function initMap() {
    // Request needed libraries.
    (await google.maps.importLibrary('places'));
    // Create the input HTML element, and append it.
    const placeAutocomplete = new google.maps.places.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-placeselect listener, and display the results.
    //prettier-ignore
    //@ts-ignore
    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);
    });
}
initMap();
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;
}

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

style.css

HTML

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

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
    </head>
    <body>
        <p style="font-family: roboto, sans-serif">Search for a place here:</p>

        <!-- 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>
    </body>
</html>
index.html

Testar amostra

Preencher um mapa automaticamente

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

TypeScript

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
const placeAutocomplete = document.querySelector(
    'gmp-place-autocomplete'
) as google.maps.places.PlaceAutocompleteElement;
let innerMap;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
let center = { lat: 40.749933, lng: -73.98633 }; // New York City
async function initMap(): Promise<void> {
    // Request needed libraries.
    const [] = await Promise.all([
        google.maps.importLibrary('marker'),
        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.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });

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

    infoWindow = new google.maps.InfoWindow({});

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

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

      let content = document.createElement('div');
      let nameText = document.createElement('span');
      nameText.textContent = place.displayName;
      content.appendChild(nameText);
      content.appendChild(document.createElement('br'));
      let addressText = document.createElement('span');
      addressText.textContent = place.formattedAddress;
      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,
    });
}

initMap();
index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
const placeAutocomplete = document.querySelector('gmp-place-autocomplete');
let innerMap;
let marker;
let infoWindow;
let center = { lat: 40.749933, lng: -73.98633 }; // New York City
async function initMap() {
    // Request needed libraries.
    const [] = await Promise.all([
        google.maps.importLibrary('marker'),
        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.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });
    // Create the marker and infowindow.
    marker = new google.maps.marker.AdvancedMarkerElement({
        map: innerMap,
    });
    infoWindow = new google.maps.InfoWindow({});
    // Add the gmp-placeselect listener, and display the results on the map.
    //prettier-ignore
    //@ts-ignore
    placeAutocomplete.addEventListener('gmp-select', async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        // 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);
        }
        let content = document.createElement('div');
        let nameText = document.createElement('span');
        nameText.textContent = place.displayName;
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        let addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress;
        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,
    });
}
initMap();
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-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: large;
    font-weight: bold;
}

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

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

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

style.css

HTML

<html>
    <head>
        <title>Place Autocomplete map</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="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
            <div
                class="place-autocomplete-card"
                slot="control-inline-start-block-start">
                <p>Search for a place here:</p>
                <gmp-place-autocomplete></gmp-place-autocomplete>
            </div>
        </gmp-map>
    </body>
</html>
index.html

Testar amostra

Usar o componente do Place Picker

O componente do seletor de lugar é uma entrada de texto que permite aos usuários finais pesquisar um endereço ou lugar específico usando o preenchimento automático. Ele faz parte da biblioteca de componentes estendida, um conjunto de componentes da Web que ajuda os desenvolvedores a criar mapas e recursos de localização melhores com mais rapidez.

Use o configurador do Place Picker para criar um código incorporável para um componente personalizado do Place Picker e exporte para usar com frameworks conhecidos, como React e Angular, ou sem nenhum framework.

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

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:

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

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

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

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.