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
(
Placereference) 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.
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:
- O ID de lugar da resposta de preenchimento automático (novo)
- O token de sessão usado na solicitação de preenchimento automático (novo)
- O parâmetro
fieldsque 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:
- O ID do lugar da resposta de preenchimento automático (novo)
- O token de sessão usado na solicitação de preenchimento automático (novo)
- O parâmetro
fieldsque 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.
-
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.
- 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.