Place Autocomplete

Selecione a plataforma: Android iOS JavaScript Web Service

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:

  1. Acesse o console do Google Cloud.
  2. Clique no botão Selecionar um projeto, escolha o que você configurou para a API Maps JavaScript e selecione Abrir.
  3. Na lista de APIs do Painel, procure API Places.
  4. Se achar a API na lista, pode prosseguir. Caso contrário, faça o seguinte para ativar a API:
    1. Na parte de cima da página, selecione ATIVAR API para abrir a guia Biblioteca. Outra opção é selecionar Biblioteca no menu lateral esquerdo.
    2. Pesquise e selecione API Places na lista de resultados.
    3. 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.
    Um campo de texto com preenchimento automático e o seletor de previsões de local fornecidas enquanto a pessoa digita a consulta de pesquisa:
    Figura 1: campo de texto de preenchimento automático e seletor
    Um formulário de endereço preenchido.
    Figura 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.
    Um formulário de endereço preenchido.
    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);
index.ts

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

index.js

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 Autocompleteatual.
  • 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);
index.ts

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

index.js
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);
index.ts

JavaScript

autocomplete.bindTo("bounds", map);

index.js

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

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.js

Exemplo

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"],
});
index.ts

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

index.js

Exemplo

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.

Demonstração

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:

  1. Crie um manipulador de eventos para o evento place_changed e coloque o addListener() no objeto Autocomplete para adicionar o manipulador.
  2. 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.

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

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;

index.js

Exemplo

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.

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.

Exemplo

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

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);
});
index.js

Exemplo

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 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.
  • place_id é um identificador textual que determina um local de forma exclusiva. Para recuperar informações sobre o lugar, transmita esse identificador no campo placeId 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;
index.ts

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;
index.js

CSS

style.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>
index.html

Testar amostra

Exemplo

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

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

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:

  1. O ID de lugar da resposta do Place Autocomplete
  2. O token de sessão usado na solicitação do Place Autocomplete
  3. 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:

  1. O ID de lugar da resposta do Place Autocomplete
  2. O token de sessão usado na solicitação do Place Autocomplete
  3. 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.

  1. 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 um usuário não escolhe uma das previsões do Autocomplete, geralmente porque nenhuma delas é o endereço de resultado desejado, você pode reutilizar a entrada original para tentar receber resultados mais relevantes:
    • Se você espera 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 subpredial, como endereços de unidades ou apartamentos específicos em um edifício. 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.