Place Autocomplete

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.

Primeiros passos

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, está tudo pronto. No entanto, esse projeto está no status legado. Para mais informações sobre a etapa legada e como migrar dela para serviços mais recentes, consulte Produtos e recursos legados. Uma exceção está disponível para os widgets Autocomplete e SearchBox, que ainda não estão disponíveis como um produto GA na API Places (New).

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

  

  

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

  

  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.

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

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.

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

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.

autocomplete.bindTo("bounds", map);
index.ts

autocomplete.bindTo("bounds", map);
index.js

Use unbind() para desvincular as previsões de preenchimento automático da janela de visualização do mapa.

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

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.

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

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.

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

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 de posição

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

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

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

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

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

style.css

<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

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.

Otimização do Place Autocomplete (legado)

Esta seção descreve as práticas recomendadas para você aproveitar ao máximo o serviço Place Autocomplete (legado).

Aqui estão algumas diretrizes gerais:

• A maneira mais rápida de desenvolver uma interface do usuário funcional é usar o widget Place Autocomplete (legado) da API Maps JavaScript, o widget Place Autocomplete (legado) do SDK do Places para Android ou o controle de IU Place Autocomplete (legado) do SDK do Places para iOS.
• Entender os campos de dados essenciais do Place Autocomplete (legado) 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 (legado), use máscaras de campo nos widgets Place Details (legado) e Place Autocomplete (legado) 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 (legado) para acessar preços por solicitação e pedir resultados da API Geocoding sobre o lugar selecionado em vez do Place Details (legado). 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 (legado).
• Se os usuários selecionarem uma previsão de preenchimento automático em média com quatro solicitações de previsão do Place Autocomplete (legado) ou menos, 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?

Práticas recomendadas de desempenho

As diretrizes a seguir descrevem como otimizar a performance do Place Autocomplete (legado):

• Adicione restrições de país, direcionamento de local e preferência de idioma (para implementações programáticas) à implementação do Place Autocomplete (legado). 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 (legado) 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 Place Autocomplete (legado), geralmente porque nenhuma delas é o endereço que ela quer, você pode reutilizar a entrada original para tentar receber resultados mais relevantes:
  • Se quiser que o usuário insira apenas informações de endereço, reutilize a entrada original dele em uma chamada para a API Geocoding.
  • Se quiser que o usuário insira consultas para um lugar específico por nome ou endereço, use uma solicitação do Find Place (legado). Se os resultados forem esperados apenas em uma região específica, use o direcionamento de local.
  Outros cenários em que é melhor voltar para a API Geocoding são:
  • Usuários que inserem endereços de subunidades, como endereços de unidades ou apartamentos específicos em um prédio. Por exemplo, o endereço tcheco "Stroupežnického 3191/17, Praha" gera uma previsão parcial no Place Autocomplete (legado).
  • 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í.

Limites de uso

Cotas

Para informações sobre preços e cotas, consulte a documentação de uso e faturamento da API Places.