Apresentação
O preenchimento automático é um recurso da biblioteca Places na API Maps JavaScript, que pode ser usado para que os apps ofereçam pesquisa durante a digitação no campo de busca do Google Maps. O serviço de preenchimento automático pode trazer palavras completas e substrings, sugerindo nomes e endereços de lugares, além de Plus Codes. À medida que a pessoa digita, os aplicativos enviam consultas e sugerem previsões de local instantaneamente. Observação: como definido pela API Places, um "lugar" pode ser um estabelecimento, uma localização geográfica ou um ponto de interesse.
Como começar
Antes de usar a biblioteca Places na API Maps JavaScript, verifique se ela está ativada no console do Google Cloud, no mesmo projeto configurado para a API Maps JavaScript.
Para saber quais são as APIs ativadas:
- Acesse o console do Google Cloud.
- Clique no botão Selecionar um projeto, escolha o que você configurou para a API Maps JavaScript e selecione Abrir.
- Na lista de APIs do Painel, procure API Places.
- Se achar a API na lista, pode prosseguir. Caso contrário, faça o seguinte para ativar a API:
- Na parte de cima da página, selecione ATIVAR API para abrir a guia Biblioteca. Outra opção é selecionar Biblioteca no menu lateral esquerdo.
- Pesquise e selecione API Places na lista de resultados.
- Clique em ATIVAR. Quando o processo terminar, a API Places vai aparecer na lista de APIs do Painel.
Carregar a biblioteca
O serviço Places é uma biblioteca independente e separada do código principal da API Maps JavaScript. Carregue essa biblioteca usando o parâmetro libraries
no URL de inicialização da API Maps para usar as funcionalidades dela:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
Consulte a Visão geral das bibliotecas para mais informações.
Resumo das classes
A API oferece dois tipos de widgets de preenchimento automático, que podem ser adicionados usando as classes Autocomplete
e SearchBox
, respectivamente.
Também é possível usar a classe AutocompleteService
para recuperar os resultados de preenchimento automático de maneira programática. Consulte a Referência da API Maps JavaScript: classe AutocompleteService.
Confira abaixo um resumo das classes disponíveis:
-
Autocomplete
adiciona um campo de entrada de texto na sua página da Web e monitora a digitação de caracteres nele. Enquanto a pessoa insere texto, o preenchimento automático traz previsões de locais na forma de uma lista suspensa de opções. Quando um local na lista é escolhido, as informações sobre ele são retornadas ao objeto de preenchimento automático e, depois, obtidas pelo seu aplicativo. Confira os detalhes abaixo.Figura 1: campo de texto de preenchimento automático e seletor Figura 2: formulário de endereço preenchido -
SearchBox
adiciona um campo de entrada de texto à sua página da Web, da mesma forma queAutocomplete
. As diferenças são as seguintes:- As principais diferenças estão nos resultados que aparecem no seletor:
SearchBox
retorna uma lista maior de previsões, que pode incluir lugares (como definido pela API Places) e os termos de pesquisa sugeridos. Por exemplo, se a pessoa digita "pizza em são", o seletor inclui a frase "pizza em São Paulo, SP" e os nomes de várias pizzarias. SearchBox
oferece menos opções queAutocomplete
para restringir a pesquisa. No primeiro caso, é possível direcionar a pesquisa para um determinadoLatLngBounds
. No segundo, você consegue restringir a pesquisa por país e tipos de local, bem como definir os limites. Para mais informações, leia abaixo.
Figura 3: um SearchBox apresenta termos de pesquisa e previsões de lugares. - As principais diferenças estão nos resultados que aparecem no seletor:
- Você pode criar um objeto
AutocompleteService
para recuperar previsões de forma programática. ChamegetPlacePredictions()
para trazer lugares correspondentes ougetQueryPredictions()
para recuperar lugares correspondentes e termos da pesquisa sugerida. Observação:AutocompleteService
não acrescenta controles de IU. Em vez disso, os métodos acima retornam uma matriz de objetos de previsão. Cada objeto de previsão contém o texto da previsão, informações de referência e detalhes sobre como o resultado corresponde à entrada do usuário. Confira os detalhes abaixo.
Adicionar um widget de preenchimento automático
O widget Autocomplete
cria um campo de entrada de texto na página da Web, oferece previsões de lugares em um seletor de IU e retorna detalhes do local em resposta a uma solicitação getPlace()
. Cada entrada no seletor corresponde a um único lugar (como definido pela API Places).
O construtor Autocomplete
usa dois argumentos:
- Um elemento HTML
input
do tipotext
. O serviço de preenchimento automático monitora esse campo e anexa os resultados a ele. - Um argumento
AutocompleteOptions
opcional, que pode conter as seguintes propriedades:- Uma matriz de dados
fields
que vai ser incluída na respostaPlace Details
do objetoPlaceResult
selecionado pelo usuário. Se a propriedade não for definida ou se['ALL']
for transmitido, todos os campos disponíveis vão ser retornados e faturados, o que não é recomendado para implantações de produção. Confira uma lista de campos emPlaceResult
. - Uma matriz de
types
que especifica um tipo explícito ou uma coleção de tipos, de acordo com os tipos compatíveis. Se nenhum tipo for especificado, todos eles vão ser trazidos. bounds
é um objetogoogle.maps.LatLngBounds
especificando a área em que locais vão ser pesquisados. Os resultados são direcionados, mas não restritos, a locais contidos nesses limites.strictBounds
é umboolean
que especifica se a API precisa retornar apenas os lugares que estão na região definida pelobounds
especificado. A API não traz resultados fora dessa região, mesmo que correspondam à entrada do usuário.componentRestrictions
pode ser usado para restringir os resultados a grupos específicos. É possível usarcomponentRestrictions
para filtrar até cinco países. Os países precisam ser transmitidos como um código de país de dois caracteres compatível com ISO 3166-1 Alfa-2. Para transmitir vários países, é preciso usar uma lista de códigos.Observação: em caso de resultados inesperados com um código de país, verifique se o código usado inclui os países, territórios dependentes e áreas especiais de interesse geográfico. Para mais detalhes sobre códigos, acesse Wikipédia: Lista de códigos de país ISO 3166 ou a Plataforma de navegação on-line ISO (links em inglês).
placeIdOnly
pode ser usado para que o widgetAutocomplete
traga apenas IDs de lugar. Quando você chamagetPlace()
no objetoAutocomplete
, as únicas propriedades definidas peloPlaceResult
disponibilizado vão serplace id
,types
ename
. É possível usar o ID de local trazido com chamadas aos serviços Places, Geocoding, Directions ou Distance Matrix.
- Uma matriz de dados
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 as opções do Place Autocomplete para mostrar previsões mais relevantes com base no caso de uso.
Definir opções na construção
O construtor Autocomplete
aceita um parâmetro AutocompleteOptions
para definir restrições na criação do widget. O exemplo a seguir define que as opções bounds
, componentRestrictions
e types
solicitem lugares do tipo establishment
, favorecendo aqueles na área geográfica especificada e restringindo as previsões aos Estados Unidos. Definir a opção fields
especifica quais informações retornar sobre o lugar que o usuário selecionou.
Chame setOptions()
para mudar o valor de uma opção de um widget atual.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input") as HTMLInputElement; const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
JavaScript
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input"); const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
Especificar campos de dados
Especifique os campos de dados para não receber faturamentos pelas SKUs de dados do Places desnecessárias. Inclua a propriedade fields
no AutocompleteOptions
, que é transmitida ao construtor do widget, como mostrado no exemplo anterior, ou chame setFields()
em um objeto Autocomplete
.
autocomplete.setFields(["place_id", "geometry", "name"]);
Definir direcionamentos e limites de área de pesquisa para preenchimento automático
Para direcionar os resultados do preenchimento automático e favorecer uma localização ou área aproximada, você pode fazer o seguinte:
- Definir os limites na criação do objeto
Autocomplete
. - Alterar os limites para um
Autocomplete
atual. - Definir os limites para a janela de visualização do mapa.
- Restringir a pesquisa aos limites.
- Restringir a pesquisa a um país específico.
O exemplo anterior mostra a definição de limites na criação. Os exemplos a seguir demonstram as outras técnicas de direcionamento.
Mudar os limites de um preenchimento automático
Chame setBounds()
para mudar a área de pesquisa em um Autocomplete
existente para limites retangulares.
TypeScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
JavaScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
Definir os limites para a janela de visualização do mapa
Use bindTo()
se quiser priorizar os resultados de acordo com a janela de visualização do mapa, mesmo enquanto essa janela é alterada.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
Use unbind()
para desvincular as previsões de preenchimento automático da janela de visualização do mapa.
TypeScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
JavaScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
Restringir a pesquisa aos limites atuais
Defina a opção strictBounds
para restringir os resultados aos limites atuais, seja com base na janela de visualização do mapa ou nos limites retangulares.
autocomplete.setOptions({ strictBounds: true });
Restringir previsões a um país
Use a opção componentRestrictions
ou chame setComponentRestrictions()
para restringir a pesquisa do preenchimento automático a até cinco países.
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
Restringir tipos de lugar
Use a opção types
ou chame setTypes()
para restringir as previsões a determinados tipos de lugares. Essa restrição especifica um ou vários tipos, como explicado em Tipos de locais.
Se nenhuma restrição for especificada, todos eles vão ser trazidos.
Para o valor da opção types
ou o valor transmitido para setTypes()
, é possível especificar:
Uma matriz que contém até cinco valores da Tabela 1 ou da Tabela 2 de Tipos de lugar. Por exemplo:
types: ['hospital', 'pharmacy', 'bakery', 'country']
Ou:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- Qualquer filtro na Tabela 3 em Tipos de locais. Só é possível especificar um valor na Tabela 3.
A solicitação vai ser rejeitada se:
- Você especificar mais de cinco tipos.
- Você especificar tipos não reconhecidos.
- Você mistura os tipos da Tabela 1 ou da Tabela 2 com qualquer filtro da Tabela 3.
A demonstração do Place Autocomplete mostra as diferenças nas previsões entre diferentes tipos de lugares.
Obter informações de lugares
Quando alguém seleciona um lugar entre as previsões anexadas ao campo de texto de preenchimento automático, o serviço aciona um evento place_changed
. Para ver detalhes de um lugar, faça o seguinte:
- Crie um manipulador de eventos para o evento
place_changed
e coloque oaddListener()
no objetoAutocomplete
para adicionar o manipulador. - Chame
Autocomplete.getPlace()
no objetoAutocomplete
para recuperar um objetoPlaceResult
, que você pode usar para conferir mais informações sobre o lugar selecionado.
Por padrão, quando alguém seleciona um lugar, o preenchimento automático traz todos os campos de dados disponíveis para ele, e uma cobrança é feita.
Use Autocomplete.setFields()
para especificar quais campos de dados de lugar precisam ser retornados. Saiba mais sobre o objeto PlaceResult
, incluindo uma lista de campos de dados de lugares que você pode pedir. Se não quiser pagar por dados desnecessários, use Autocomplete.setFields()
para especificar somente os dados do lugar que você vai usar.
A propriedade name
contém o description
das previsões de preenchimento automático de lugares. Saiba mais sobre o description
na documentação de preenchimento automático de lugares.
Para formulários de endereço, convém consultar o endereço no formato estruturado. Se quiser trazer o endereço estruturado do lugar selecionado, chame Autocomplete.setFields()
e especifique o campo address_components
.
O exemplo a seguir usa preenchimento automático para preencher os campos em um formulário de endereço.
TypeScript
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": (document.querySelector("#locality") as HTMLInputElement).value = component.long_name; break; case "administrative_area_level_1": { (document.querySelector("#state") as HTMLInputElement).value = component.short_name; break; } case "country": (document.querySelector("#country") as HTMLInputElement).value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); }
JavaScript
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": document.querySelector("#locality").value = component.long_name; break; case "administrative_area_level_1": { document.querySelector("#state").value = component.short_name; break; } case "country": document.querySelector("#country").value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); } window.initAutocomplete = initAutocomplete;
Personalizar o texto do marcador
Por padrão, o campo de texto criado pelo serviço de preenchimento automático contém texto de marcadores de posição padrão. Para modificar o texto, defina o atributo
placeholder
no elemento input
:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Observação: o texto do marcador de posição padrão é localizado automaticamente. Para especificar seu valor de marcador de posição, é necessário processar a localização desse valor no aplicativo. Para mais informações sobre como a API Google Maps JavaScript escolhe o idioma a ser usado, leia a documentação sobre localização.
Consulte Como definir o estilo dos widgets Autocomplete e SearchBox para personalizar a aparência do widget.
Adicionar um widget SearchBox
Com o SearchBox
, o usuário consegue executar uma pesquisa geográfica com base em texto, como "pizza em São Paulo" ou "lojas de sapatos perto da Avenida Paulista".
Você pode anexar SearchBox
a um campo de texto e, à medida que o texto for inserido, o serviço vai retornar previsões como uma lista suspensa.
SearchBox
oferece uma lista grande de previsões, que pode incluir lugares (como definido pela API Places), além de termos de pesquisa sugeridos. Por exemplo, se a pessoa digita "pizza em são", o seletor inclui a frase "pizza em São Paulo, SP" e os nomes de várias pizzarias. Quando a pessoa seleciona um lugar na lista, as informações sobre ele são retornadas ao objeto SearchBox e podem ser recuperadas pelo aplicativo.
O construtor SearchBox
usa dois argumentos:
- Um elemento HTML
input
do tipotext
. O serviçoSearchBox
monitora esse campo e anexa os resultados a ele. - Um argumento
options
, que pode incluir a propriedadebounds
:bounds
é um objetogoogle.maps.LatLngBounds
que especifica a área onde pesquisar os lugares. Os resultados são direcionados, mas não restritos, a locais contidos nesses limites.
O código a seguir usa o parâmetro bounds para direcionar os resultados a locais em uma determinada área geográfica, especificada por coordenadas de latitude e longitude.
var defaultBounds = new google.maps.LatLngBounds( new google.maps.LatLng(-33.8902, 151.1759), new google.maps.LatLng(-33.8474, 151.2631)); var input = document.getElementById('searchTextField'); var searchBox = new google.maps.places.SearchBox(input, { bounds: defaultBounds });
Alterar a área de pesquisa do SearchBox
Para mudar a área de pesquisa de um SearchBox
atual, chame setBounds()
no objeto SearchBox
e transmita o objeto LatLngBounds
relevante.
Obter informações de lugares
Quando a pessoa seleciona um item das previsões anexadas à caixa de pesquisa, o serviço dispara um evento places_changed
. Chame getPlaces()
no objeto SearchBox
para recuperar uma matriz com várias previsões, cada uma sendo um objeto PlaceResult
.
Para mais informações sobre o objeto PlaceResult
, consulte a documentação sobre resultados de detalhes de lugares.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon as string, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }) ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
JavaScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }), ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
Consulte Como definir o estilo dos widgets Autocomplete e SearchBox para personalizar a aparência do widget.
Recuperar programaticamente previsões do serviço Place Autocomplete
Para trazer previsões de forma programática, use a classe AutocompleteService
. AutocompleteService
não acrescenta controles de IU. Em vez disso, traz uma matriz de objetos de previsão, cada um deles com referências e detalhes sobre como o resultado corresponde à entrada do usuário.
Isso é útil se você quer mais controle sobre a interface do usuário do que é oferecido por Autocomplete
e SearchBox
acima.
AutocompleteService
expõe os seguintes métodos:
getPlacePredictions()
retorna previsões de lugares. Observação: um "local" pode ser um estabelecimento, uma localização geográfica ou um ponto de interesse importante, conforme definido pela API Places.getQueryPredictions()
traz uma extensa lista de previsões, que pode incluir lugares (como definido pela API Places), além de termos de pesquisa sugerida. Por exemplo, se a pessoa digita "pizza em são", o seletor inclui a frase "pizza em São Paulo, SP" e os nomes de várias pizzarias.
Os dois métodos acima retornam uma matriz de objetos de previsão da seguinte forma:
description
é a previsão correspondente.distance_meters
é a distância em metros do lugar a partir doAutocompletionRequest.origin
especificado.matched_substrings
contém um conjunto de substrings na descrição que corresponde a elementos na entrada do usuário. Isso é útil para destacar essas substrings no aplicativo. Em muitos casos, a consulta aparece como uma substring do campo de descrição.length
é o comprimento da substring.offset
é o deslocamento em caracteres em que a substring aparece, medido do início da string de descrição.
place_id
é um identificador textual que determina um local de forma exclusiva. Para recuperar informações sobre o lugar, transmita esse identificador no campoplaceId
de uma solicitação do Place Details. Saiba mais sobre como fazer referência a um local com o respectivo código.terms
é uma matriz contendo elementos da consulta. Normalmente, cada elemento é uma parte do endereço de um local.offset
é o deslocamento em caracteres em que a substring aparece, medido do início da string de descrição.value
é o termo correspondente.
O exemplo abaixo executa uma solicitação de previsão de consulta para a frase "pizza por perto" e mostra o resultado em uma lista.
TypeScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService(): void { const displaySuggestions = function ( predictions: google.maps.places.QueryAutocompletePrediction[] | null, status: google.maps.places.PlacesServiceStatus ) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); (document.getElementById("results") as HTMLUListElement).appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } declare global { interface Window { initService: () => void; } } window.initService = initService;
JavaScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initService() { const displaySuggestions = function (predictions, status) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); document.getElementById("results").appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } window.initService = initService;
CSS
HTML
<html> <head> <title>Retrieving Autocomplete Predictions</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <p>Query suggestions for 'pizza near Syd':</p> <ul id="results"></ul> <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements --> <img class="powered-by-google" src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png" alt="Powered by Google" /> <!-- The `defer` attribute causes the script to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly" defer ></script> </body> </html>
Testar amostra
Tokens de sessão
AutocompleteService.getPlacePredictions()
pode usar tokens de sessão (se implementados) para agrupar solicitações de preenchimento automático para fins de faturamento. Os tokens de sessão agrupam as fases de consulta e seleção de uma pesquisa de preenchimento automático do usuário em uma sessão discreta para fins de faturamento. A sessão inicia quando a pessoa começa a digitar uma consulta e termina quando seleciona um local. Cada sessão pode ter várias consultas, seguidas por uma seleção de lugar.
Após a conclusão de uma sessão, o token perde a validade. Seu aplicativo precisa gerar um novo token para cada sessão. Recomendamos o uso de tokens de sessão em todas as sessões de preenchimento automático. Se o parâmetro sessionToken
for omitido ou você reutilizar um token, a sessão vai ser cobrada como se nenhum token de sessão tivesse sido fornecido e cada solicitação será faturada separadamente.
Você pode usar o mesmo token de sessão para fazer uma única solicitação do Place Details no lugar que vem de uma chamada para AutocompleteService.getPlacePredictions()
.
Nesse caso, a solicitação de autopreenchimento é combinada com a do Place Details, e a chamada é cobrada como uma solicitação normal do Place Details. Não há cobrança para a solicitação de preenchimento automático.
Transmita um token de sessão exclusivo para cada sessão nova. Se você usar o mesmo token para mais de uma sessão de autopreenchimento, isso vai invalidar as sessões, e todas as solicitações de preenchimento automático nelas vão ser cobradas individualmente com o SKU Autocomplete – por solicitação. Saiba mais sobre tokens de sessão.
O exemplo a seguir mostra como criar e transmitir um token de sessão em um AutocompleteService
(a função displaySuggestions()
foi omitida para simplificar):
// Create a new session token. var sessionToken = new google.maps.places.AutocompleteSessionToken(); // Pass the token to the autocomplete service. var autocompleteService = new google.maps.places.AutocompleteService(); autocompleteService.getPlacePredictions({ input: 'pizza near Syd', sessionToken: sessionToken }, displaySuggestions);
Transmita um token de sessão exclusivo para cada sessão nova. Se você usar o mesmo token para mais de uma sessão, cada solicitação vai ser faturada individualmente.
Saiba mais sobre tokens de sessão.
Definir o estilo dos widgets Autocomplete e SearchBox
Por padrão, os elementos da IU fornecidos por Autocomplete
e SearchBox
são estilizados para inclusão em um mapa do Google. Se quiser, ajuste o estilo de acordo com seu site. As classes CSS a seguir estão disponíveis. Todas as classes listadas abaixo se aplicam aos widgets Autocomplete
e SearchBox
.
![Uma ilustração das classes CSS para os widgets Autocomplete e SearchBox](https://google-developers.gonglchuangl.net/static/maps/documentation/javascript/images/place-autocomplete-css-diagram.png?hl=pt)
Classe CSS | Descrição |
---|---|
pac-container |
O elemento visual contendo a lista de previsões retornadas pelo serviço Place Autocomplete. Ela aparece como uma lista suspensa abaixo do widget Autocomplete ou SearchBox . |
pac-icon |
O ícone à esquerda de cada item na lista de previsões. |
pac-item |
Um item na lista de previsões fornecidas pelo widget Autocomplete ou SearchBox . |
pac-item:hover |
O item sobre o qual a pessoa passa o ponteiro do mouse. |
pac-item-selected |
O item selecionado pela pessoa usando o teclado. Observação: os itens selecionados vão ser membros desta classe e da classe pac-item .
|
pac-item-query |
Um período dentro de um pac-item que é a parte principal da previsão. Para localizações geográficas, contém um nome de local, como "São Paulo", ou um nome e número de rua, como "Rua Teodoro Sampaio, 10". Para pesquisas em texto, como "pizza em São Paulo", contém o texto completo da consulta. Por padrão, pac-item-query fica em preto. Qualquer outro texto no pac-item vai estar fora de pac-item-query e herdar o estilo de pac-item . A cor padrão é cinza. Normalmente, o texto adicional é um endereço. |
pac-matched |
A parte da previsão retornada que corresponde à entrada do usuário. Por padrão, esse texto correspondido fica em negrito. O texto relacionado pode estar em qualquer lugar em pac-item . Ele não necessariamente faz parte de pac-item-query e pode estar parcialmente em pac-item-query ou, em parte, no texto restante em pac-item . |
Usar o componente do Place Picker
Observação: este exemplo usa uma biblioteca de código aberto. Confira o README para receber suporte e feedback relacionados à biblioteca.
Teste componentes da Web. Use o componente da Web do Place Picker para ativar uma entrada de texto que permita aos usuários finais pesquisar um endereço ou lugar específico usando o preenchimento automático.
![GIF com caixa de pesquisa. O usuário começa a digitar um endereço como entrada, e um menu suspenso com endereços relacionados é exibido. Ele clica em um endereço no menu suspenso, e a caixa de pesquisa preenche o restante do endereço.](https://google-developers.gonglchuangl.net/static/maps/documentation/javascript/images/place-picker.gif?hl=pt)
Otimização do Place Autocomplete
Esta seção descreve as práticas recomendadas para você aproveitar ao máximo o serviço Place Autocomplete.
Aqui estão algumas diretrizes gerais:
- A maneira mais rápida de desenvolver uma interface do usuário funcional é usar o widget do Autocomplete da API Maps JavaScript, o widget do Autocomplete do SDK do Places para Android ou Controle de IU do Autocomplete do SDK do Places para iOS.
- Entender os campos de dados essenciais do Place Autocomplete 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 Place Autocomplete, use máscaras de campo nos widgets Place Details e Place Autocomplete para retornar apenas os campos de dados de lugar necessários.
Otimização avançada de custos
Faça a implementação programática do Place Autocomplete para acessar preços por solicitação e pedir resultados da API Geocoding sobre o lugar selecionado em vez do Place Details. 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.
- 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 Place Autocomplete com base em sessões com o Place Details.
Como seu app exige detalhes do lugar, como nome, status comercial ou horário de funcionamento, a implementação do preenchimento automático precisa usar um token de sessão (de forma programática ou integrada aos widgets do JavaScript, Android ou iOS) a um total de US$ 0,017 por sessão, além de SKU de dados 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 widgets do JavaScript, Android ou iOS. Isso inclui as solicitações do Place Autocomplete e do Place Details na previsão selecionada. Especifique o parâmetro fields
para garantir que você está pedindo apenas os campos de dados de lugares necessários.
Implementação programática
Use um token de sessão com suas solicitações do Place Autocomplete. Ao solicitar Place Details sobre a previsão selecionada, inclua os seguintes parâmetros:
- O ID de lugar da resposta do Place Autocomplete
- O token de sessão usado na solicitação do Place Autocomplete
- O parâmetro
fields
especificando os campos de dados de lugar 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 para seu aplicativo, dependendo da performance do Place Autocomplete. A eficiência do preenchimento automático 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 Place Autocomplete no seu aplicativo.
As pessoas selecionam, em média, uma previsão do Place Autocomplete em até quatro solicitações?
Sim
Implementar o Place Autocomplete 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 por US$ 0,005 a cada solicitação. Fazer quatro solicitações de Place Autocomplete: por solicitação custa US$ 0,01132. Portanto, o custo total de quatro solicitações, além de uma chamada da API Geocoding sobre a previsão de lugar selecionada, é de US$ 0,01632, menor que o preço de preenchimento automático por sessão de US$ 0,017.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 Place Autocomplete com base em sessões com o Place Details.
Como a média de solicitações que você espera fazer antes de alguém selecionar uma previsão do Place Autocomplete é maior que o custo do preço por sessão, a implementação do Place Autocomplete precisa usar um token de sessão para as solicitações do Place Autocomplete e a respectiva solicitação do Place Details por um total de US$ 0,017 a cada 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 Place Autocomplete e do Place Details na previsão selecionada. Especifique o parâmetro fields
para garantir a solicitação apenas dos campos de dados básicos.
Implementação programática
Use um token de sessão com suas solicitações do Place Autocomplete. Ao solicitar Place Details sobre a previsão selecionada, inclua os seguintes parâmetros:
- O ID de lugar da resposta do Place Autocomplete
- O token de sessão usado na solicitação do Place Autocomplete
- O parâmetro
fields
que especifica campos de dados básicos como endereço e geometria
Considere atrasar as solicitações do Place Autocomplete
É possível adiar uma solicitação do Place Autocomplete 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 do Place Autocomplete 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 vai ser de US$ 0,01632 (4 × US$ 0,00283 do Autocomplete por solicitação + US$ 0,005 do 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 Place Autocomplete 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.
-
Os custos listados aqui estão em USD. Consulte a página Faturamento da Plataforma Google Maps para saber tudo sobre os preços.
Práticas recomendadas de performance
As diretrizes a seguir descrevem como otimizar a performance do Place Autocomplete:
- Adicione restrições de país, direcionamento de local e preferência de idioma (para implementações programáticas) à implementação do Place Autocomplete. 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 Place Autocomplete 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, geralmente porque nenhuma delas revisões é 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 Find Place. Se os resultados forem esperados apenas em uma região específica, use o direcionamento de local.
- Usuários que inserem endereços de sublocal em países onde a compatibilidade do Place Autocomplete com esse tipo de endereço é parcial (como República Tcheca, Estônia e Lituânia). Por exemplo, o endereço tcheco "Stroupežnického 3191/17, Praha" gera uma previsão parcial no Place Autocomplete.
- 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í.
Políticas e limites de uso
Cotas
Para informações sobre preços e cotas, consulte a documentação de uso e faturamento da API Places.
Políticas
A biblioteca Places e a API Maps JavaScript precisam ser usadas de acordo com as políticas da API Places.