Em breve, a Plataforma Google Maps usará a nova estilização de mapas. Essa atualização inclui uma nova paleta de cores padrão e melhorias nas experiências de mapa e na usabilidade. Todos os estilos de mapa serão atualizados automaticamente em março de 2025. Para mais informações sobre a disponibilidade e como ativar logo, consulte Novo estilo de mapa para a Plataforma Google Maps.
Nesta página, descrevemos a biblioteca do lado do cliente disponível com a API Maps JavaScript. Se você quiser trabalhar com o serviço da Web da API Places no seu servidor, consulte o Cliente Node.js para serviços do Google Maps. A página no link também apresenta o Cliente Java, Cliente Python e Cliente Go para serviços do Google Maps.
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.
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:
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 seletorFigura 2: formulário de endereço preenchido
SearchBox adiciona um campo de entrada de texto à sua página da Web, da mesma forma que Autocomplete. 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 que Autocomplete para restringir a pesquisa. No primeiro caso, é possível direcionar a pesquisa para um determinado LatLngBounds. 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.
Confira os detalhes abaixo.
Você pode criar um objeto AutocompleteService para recuperar previsões de forma programática. Chame getPlacePredictions() para trazer lugares correspondentes ou getQueryPredictions() 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 tipo text. 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 resposta Place Details do objeto PlaceResult 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 em PlaceResult.
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 objeto google.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 é um boolean que especifica se a API precisa retornar apenas os lugares que estão na região definida pelo bounds 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 usar componentRestrictions 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 widget Autocomplete traga apenas IDs de lugar. Quando você chama getPlace() no objeto Autocomplete, as únicas propriedades definidas pelo PlaceResult disponibilizado vão ser place id, types e name. É possível usar o ID de local trazido com chamadas aos serviços Places, Geocoding, Directions ou Distance Matrix.
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);
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.
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.
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:
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 o addListener() no objeto Autocomplete para adicionar o manipulador.
Chame Autocomplete.getPlace() no objeto Autocomplete para recuperar um objeto PlaceResult, 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.
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();
}
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;
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.
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 tipo text. O serviço SearchBox monitora esse campo e anexa os resultados a ele.
Um argumento options, que pode incluir a propriedade bounds: bounds é um objeto google.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.
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.
// 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);
});
// 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);
});
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 do AutocompletionRequest.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.
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;
// 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;
<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>
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.
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.
Classes CSS para os widgets Autocomplete e SearchBox
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.
Figura 1: entrada de texto para pesquisar um endereço ou lugar específico usando o preenchimento automático
Otimização do Place Autocomplete
Esta seção descreve as práticas recomendadas para você aproveitar ao máximo o serviço Place Autocomplete.
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.
Se quiser ajuda para escolher a implementação do Place Autocomplete 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?
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.
Outros cenários em que é melhor voltar para a API Geocoding são:
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í.
