Place Autocomplete

Selecione a plataforma: Android iOS JavaScript Serviço da Web

Introdução

O preenchimento automático é um recurso da biblioteca do Places na API Maps JavaScript. Você pode usar o preenchimento automático para oferecer aos seus aplicativos o comportamento de pesquisa antecipada do campo do Google Maps. O serviço de preenchimento automático pode corresponder a palavras completas e substrings, resolvendo nomes de lugares, endereços e códigos Plus. Os aplicativos podem enviar consultas conforme o usuário digita, para fornecer previsões de lugares em tempo real.

Primeiros passos

Antes de usar a biblioteca do Places na API Maps JavaScript, verifique se ela está ativada no Console do Google Cloud, no mesmo projeto que você configurou para a API Maps JavaScript.

Para ver a lista de APIs ativadas:

  1. Acesse o Console do Google Cloud.
  2. Clique no botão Selecionar um projeto, escolha o mesmo projeto configurado para a API Maps JavaScript e clique em Abrir.
  3. Na lista de APIs do Painel, procure API Places.
  4. Se achar a API na lista, está tudo pronto. Se a API não estiver listada, ative-a:
    1. Na parte superior da página, selecione ATIVAR API para exibir a guia Biblioteca. Como alternativa, no menu lateral à esquerda, selecione Biblioteca.
    2. Pesquise API Places e selecione-a na lista de resultados.
    3. Selecione ATIVAR. Quando o processo for concluído, a API Places aparecerá na lista de APIs do Painel.

Carregar a biblioteca

O serviço Places é uma biblioteca independente, separada do código principal da API Maps JavaScript. Para usar a funcionalidade dessa biblioteca, você precisa primeiro carregá-la usando o parâmetro libraries no URL de inicialização da API Maps:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

Consulte 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. Além disso, você pode 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.

Veja a seguir um resumo das classes disponíveis:

  • Autocomplete adiciona um campo de entrada de texto à sua página da Web e monitora esse campo em busca de entradas de caracteres. À medida que o usuário digita texto, o preenchimento automático retorna previsões de lugares na forma de uma lista suspensa. Quando o usuário seleciona um lugar da lista, as informações sobre o local são retornadas ao objeto de preenchimento automático e podem ser recuperadas pelo aplicativo. Veja os detalhes abaixo.
    Um campo de texto de preenchimento automático e a lista de seleção de previsões de lugares fornecidos à medida que o usuário insere a consulta de pesquisa.
    Figura 1: campo de texto e preenchimento automático da lista
    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 maneira que Autocomplete. Veja as diferenças abaixo:
    • A principal diferença está nos resultados que aparecem na lista de seleção. SearchBox fornece uma lista estendida de previsões, que pode incluir lugares (conforme definido pela API Places), além de termos de pesquisa sugeridos. Por exemplo, se o usuário inserir "#39;pizza em São Paulo& novo", a lista de seleção poderá incluir a frase "#39;pizza em São Paulo, SP' bem como os nomes de várias pizzarias".
    • SearchBox oferece menos opções que Autocomplete para restringir a pesquisa. No primeiro caso, você pode polarizar a pesquisa para um determinado LatLngBounds. Com a segunda opção, é possível restringir a pesquisa a um determinado país e tipos de lugar específicos, bem como definir os limites. Para mais informações, veja abaixo.
    Um formulário de endereço preenchido.
    Figura 3: uma caixa de pesquisa apresenta termos de pesquisa e previsões de lugares.
    Veja os detalhes abaixo.
  • Você pode criar um objeto AutocompleteService para recuperar previsões de forma programática. Chame getPlacePredictions() para recuperar lugares correspondentes ou getQueryPredictions() para recuperar lugares correspondentes e termos de pesquisa sugeridos. Observação: o AutocompleteService não adiciona 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, além de informações de referência e detalhes de como o resultado corresponde à entrada do usuário. Veja os detalhes abaixo.

Adicionar um widget de preenchimento automático

O widget Autocomplete cria um campo de entrada de texto na sua página da Web, fornece previsões de lugares em uma lista de seleção de IU e retorna detalhes do lugar em resposta a uma solicitação getPlace(). Cada entrada na lista corresponde a um único lugar (conforme definido pela API Places).

O construtor Autocomplete usa dois argumentos:

  • Um elemento HTML input do tipo text. Este é o campo de entrada que o serviço de preenchimento automático vai monitorar e anexar os resultados.
  • Um argumento AutocompleteOptions opcional, que pode conter as seguintes propriedades:
    • Uma matriz de dados fields a ser incluída na resposta Place Details do PlaceResult selecionado pelo usuário. Se a propriedade não for definida ou se ['ALL'] for transmitido, todos os campos disponíveis serão retornados e faturados por, o que não é recomendado para implantações de produção. Veja uma lista de campos em PlaceResult.
    • Uma matriz de types que especifica um tipo explícito ou uma coleção de tipos, conforme listado nos tipos compatíveis. Se nenhum tipo for especificado, todos os tipos serão retornados.
    • bounds é um objeto google.maps.LatLngBounds que especifica a área em que pesquisa lugares. Os resultados são direcionados, mas não restritos, a lugares contidos nesses limites.
    • strictBounds é um boolean que especifica se a API precisa retornar apenas os lugares que estão estritamente dentro da região definida pelo bounds especificado. A API não retorna resultados fora dessa região, mesmo que correspondam à entrada do usuário.
    • componentRestrictions pode ser usado para restringir os resultados a grupos específicos. No momento, é possível usar componentRestrictions para filtrar por 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. É necessário transmitir vários países como uma lista de códigos.

      Observação: se você receber resultados inesperados com um código de país, verifique se está usando um código que inclui os países, territórios dependentes e áreas especiais de interesse geográfico. Você pode encontrar informações sobre código em Wikipédia: lista de códigos de país ISO 3166 ou na Plataforma de navegação on-line ISO (em inglês).

    • placeIdOnly pode ser usado para instruir o widget Autocomplete para recuperar apenas IDs de lugar. Ao chamar getPlace() no objeto Autocomplete, o PlaceResult disponibilizado terá apenas as propriedades place id, types e name definidas. Você pode usar o ID de lugar retornado com chamadas para os 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 local, tendenciosos para previsões perto da localização do usuário e busca todos os campos de dados disponíveis para o local selecionado pelo usuário. Defina as opções do Place Autocomplete para apresentar previsões mais relevantes com base no seu caso de uso.

Definir opções de construção

O construtor Autocomplete aceita um parâmetro AutocompleteOptions para definir restrições na criação do widget. O exemplo a seguir define as opções bounds, componentRestrictions e types para solicitar lugares do tipo establishment, favorecendo aqueles dentro da área geográfica especificada e restringindo previsões para apenas lugares nos Estados Unidos. Definir a opção fields especifica quais informações retornar sobre o lugar selecionado pelo usuário.

Chamar setOptions() para mudar o valor de uma opção de um widget existente.

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,
  types: ["establishment"],
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

JavaScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Especificar campos de dados

Especifique os campos de dados para não receber cobranças pelas SKUs de dados do Places que não são necessárias. Inclua a propriedade fields no AutocompleteOptions, que é transmitida ao construtor do widget, como demonstrado no exemplo anterior, ou chame setFields() em um objeto Autocomplete atual.

autocomplete.setFields(["place_id", "geometry", "name"]);

Definir vieses e limites de áreas de pesquisa no Autocomplete

É possível polarizar os resultados do preenchimento automático para favorecer um local ou uma área aproximada, das seguintes maneiras:

  • Defina os limites na criação do objeto Autocomplete.
  • Mude os limites de um Autocomplete
  • Definir os limites para a janela de visualização do mapa.
  • Restrinja a pesquisa aos limites.
  • Restrinja a pesquisa a um país específico.

O exemplo anterior demonstra os limites de configuração na criação. Os exemplos a seguir demonstram as outras técnicas de viés.

Alterar os limites de um Autocomplete existente

Chame setBounds() para mudar a área de pesquisa em uma Autocomplete existente para limites retangulares.

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

JavaScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
Definir os limites para a janela de visualização do mapa.

Use bindTo() para polarizar os resultados na janela de visualização do mapa, mesmo que ela mude.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

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

TypeScript

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

JavaScript

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

Ver 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 para um país específico

Use a opção componentRestrictions ou chame setComponentRestrictions() para restringir a pesquisa do preenchimento automático a um conjunto específico de até cinco países.

TypeScript

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

JavaScript

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

Ver exemplo

Restringir tipos de lugar

Use a opção types ou chame setTypes() para restringir as previsões a determinados tipos de lugar. Essa restrição especifica um tipo ou uma coleção de tipos, conforme listado em Tipos de lugares. Se nenhuma restrição for especificada, todos os tipos serão retornados.

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 lugares. Exemplo:

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    ou:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Qualquer filtro na Tabela 3 de Tipos de lugar. Só é possível especificar um único valor na Tabela 3.

A solicitação será rejeitada se:

  • Você especifica mais de cinco tipos.
  • Especifique os 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 Places Autocomplete demonstra as diferenças nas previsões entre diferentes tipos de lugares.

Acessar demonstração

Receber informações do lugar

Quando um usuário 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 chame 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 ver mais informações sobre o lugar selecionado.

Por padrão, quando um usuário seleciona um lugar, o preenchimento automático retorna todos os campos de dados disponíveis para o local selecionado, e você é cobrado. Use Autocomplete.setFields() para especificar quais campos de dados de lugar serão retornados. Saiba mais sobre o objeto PlaceResult, incluindo uma lista de campos de dados de lugar que você pode solicitar. Para evitar pagar por dados de que você não precisa, use Autocomplete.setFields() para especificar somente os dados do local que será usado.

A propriedade name contém o description das previsões do Places Autocomplete. Saiba mais sobre o description na documentação do Place Autocomplete.

Para formulários de endereço, é útil consultar o endereço no formato estruturado. Para retornar o endereço estruturado do lugar selecionado, chame Autocomplete.setFields() e especifique o campo address_components.

O exemplo a seguir usa o preenchimento automático para preencher os campos em um formulário de endereço.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;

Ver 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 marcador 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. Se você especificar seu próprio valor de marcador, será necessário processar a localização desse valor no aplicativo. Para informações sobre como a API Maps JavaScript escolhe a linguagem a ser usada, leia a documentação sobre localização.

Consulte Como definir o estilo dos widgets Autocomplete e SearchBox para personalizar a aparência do widget.

O SearchBox permite que os usuários realizem uma pesquisa geográfica com base em texto, como 'pizza em Nova York' ou 'lojas de sapato perto da rua robson'. É possível anexar SearchBox a um campo de texto e, conforme o texto for inserido, o serviço retornará previsões na forma de uma lista suspensa de opções.

SearchBox fornece uma lista estendida de previsões, que pode incluir lugares (conforme definido pela API Places), além de termos de pesquisa sugeridos. Por exemplo, se o usuário inserir 'pizza em novo', a lista de seleção poderá incluir a frase 'pizza em Nova York, NY&#39, bem como os nomes de várias pizzarias. Quando um usuário seleciona um lugar na lista, as informações sobre esse lugar são retornadas ao objeto SearchBox e podem ser recuperadas pelo app.

O construtor SearchBox usa dois argumentos:

  • Um elemento HTML input do tipo text. Esse é o campo de entrada que o serviço SearchBox vai monitorar e anexar aos resultados.
  • Um argumento options, que pode conter a propriedade bounds: bounds é um objeto google.maps.LatLngBounds que especifica a área em que é preciso pesquisar lugares. Os resultados são enviesados, mas não restritos, a lugares contidos nesses limites.

O código a seguir usa o parâmetro limites para direcionar os resultados a locais dentro de uma área geográfica específica, especificados por coordenadas de latitude/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
});

Como alterar a área de pesquisa do SearchBox

Para mudar a área de pesquisa de uma SearchBox atual, chame setBounds() no objeto SearchBox e transmita o objeto LatLngBounds relevante.

Ver exemplo

Receber informações do lugar

Quando o usuário seleciona um item nas previsões anexadas à caixa de pesquisa, o serviço aciona um evento places_changed. Você pode chamar getPlaces() no objeto SearchBox para recuperar uma matriz que contenha várias previsões, cada uma sendo um objeto PlaceResult.

Para mais informações sobre o objeto PlaceResult, consulte a documentação sobre resultados de detalhes de lugares.

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

JavaScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

Ver exemplo

Consulte Como definir o estilo dos widgets Autocomplete e SearchBox para personalizar a aparência do widget.

Como recuperar programaticamente previsões do serviço Place Autocomplete

Para recuperar programaticamente previsões, use a classe AutocompleteService. AutocompleteService não adiciona controles de IU. Em vez disso, ela retorna uma matriz de objetos de previsão, cada um com o texto da previsão, informações de referência e detalhes de como o resultado corresponde à entrada do usuário. Isso é útil se você quer mais controle sobre a interface do usuário do que o que é oferecido por Autocomplete e SearchBox, descritos acima.

AutocompleteService expõe os seguintes métodos:

  • getPlacePredictions() retorna previsões de lugares. Observação: um 'place' pode ser um estabelecimento, uma localização geográfica ou um ponto de interesse de destaque, conforme definido pela API Places.
  • getQueryPredictions() retorna uma lista estendida de previsões, que pode incluir lugares (conforme definido pela API Places) e termos de pesquisa sugeridos. Por exemplo, se o usuário inserir "#39;pizza em São Paulo& novo", a lista de seleção poderá incluir a frase "#39;pizza em São Paulo, SP' bem como 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 aos elementos na entrada do usuário. Isso é útil para destacar essas substrings no aplicativo. Em muitos casos, a consulta aparecerá como uma substring do campo de descrição.
    • length é o comprimento da substring.
    • offset é o deslocamento de caracteres, medido a partir do início da string de descrição, em que a substring correspondente aparece.
  • place_id é um identificador textual que identifica exclusivamente um lugar. Para recuperar informações sobre o local, transmita esse identificador no campo placeId de uma solicitação do Place Details. Saiba mais sobre como fazer referência a um lugar com um código de lugar.
  • terms é uma matriz que contém elementos da consulta. Para um lugar, cada elemento geralmente constitui uma parte do endereço.
    • offset é o deslocamento de caracteres, medido a partir do início da string de descrição, em que a substring correspondente aparece.
    • value é o termo correspondente.

O exemplo abaixo executa uma solicitação de previsão de consulta para a frase &&39;pizza near' e exibe o resultado em uma lista.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

JavaScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <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 callback 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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

Testar amostra

Ver exemplo

Tokens de sessão

O AutocompleteService.getPlacePredictions() usa tokens de sessão 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 começa quando o usuário começa a digitar uma consulta e termina quando ele seleciona um lugar. 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 não será mais válido. Seu app 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 se você reutilizar um token, a sessão será cobrada como se nenhum token de sessão tivesse sido fornecido (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 resulta de uma chamada para AutocompleteService.getPlacePredictions(). Nesse caso, a solicitação do Autocomplete é combinada com a solicitação 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 nova sessão. Usar o mesmo token para mais de uma sessão do Autocomplete invalidará essas sessões, e toda a solicitação do Autocomplete nas sessões inválidas será cobrada individualmente com o SKU do Autocomplete Per Request. Leia mais sobre tokens de sessão.

O exemplo a seguir mostra a criação de um token de sessão e a transmissão dele em uma 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 nova sessão. Se você usar o mesmo token para mais de uma sessão, cada solicitação será faturada individualmente.

Leia mais sobre tokens de sessão.

Como 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. Talvez você queira ajustar o estilo de acordo com seu site. As seguintes classes CSS estão disponíveis. Todas as classes listadas abaixo se aplicam aos widgets Autocomplete e SearchBox.

Uma ilustração gráfica das classes CSS para os widgets Autocomplete e SearchBox
Classes CSS para widgets do Autocomplete e SearchBox
Classe CSS Descrição
pac-container O elemento visual que contém a lista de previsões retornadas pelo serviço Place Autocomplete. Esta lista aparece como uma lista suspensa abaixo do widget Autocomplete ou SearchBox.
pac-icon O ícone exibido à 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 o usuário passa o ponteiro do mouse.
pac-item-selected O item selecionado pelo usuário por meio do teclado. Observação: os itens selecionados serão 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, isso contém o nome de um lugar, como 'Sydney' ou o nome e número da rua, como '10 King Street'. Para pesquisas baseadas em texto, como "#39;pizza em São Paulo'", ela contém o texto completo da consulta. Por padrão, a pac-item-query é colorida em preto. Se houver outro texto no pac-item, ele estará fora de pac-item-query e herdará o estilo do pac-item. Sua cor padrão é cinza. O texto adicional normalmente é um endereço.
pac-matched A parte da previsão retornada que corresponde à entrada do usuário. Por padrão, esse texto correspondente é destacado em negrito. O texto correspondente pode estar em qualquer lugar em pac-item. Não é necessariamente parte de pac-item-query e pode estar parcialmente em pac-item-query, e também em parte no texto restante em pac-item.

Otimização do Place Autocomplete

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

Veja 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 o controle da 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 viés de local e restrição de local são opcionais, mas podem ter um impacto significativo no desempenho do preenchimento automático.
  • Use o tratamento de erros para garantir que o app faça uma degradação suave se a API retornar um erro.
  • Verifique se o app processa quando não há seleção e oferece aos usuários 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 de Place Details e Place Autocomplete para retornar apenas os campos de dados de lugar necessários.

Otimização avançada de custos

Considere a implementação programática do Place Autocomplete para acessar preços por solicitação e solicitar resultados da API Geocoding sobre o lugar selecionado em vez do Place Details. O preço por solicitação combinado à API Geocoding é mais econômico que o preço por sessão (com base na sessão) se as duas condições a seguir forem atendidas:

  • Se você precisar apenas da latitude/longitude ou do endereço do lugar selecionado pelo usuário, a API Geocoding fornecerá essas informações para menos do que uma chamada de 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.
Para receber ajuda para escolher a implementação do Place Autocomplete adequada às suas necessidades, selecione a guia que corresponde à resposta à pergunta abaixo.

Seu aplicativo requer outras informações que não sejam o endereço e a latitude/longitude da previsão selecionada?

Sim, precisa de mais detalhes

Use o Place Autocomplete com base em sessões com o Place Details.
Como seu aplicativo exige o Place Details, como nome do local, status de negócios ou horário de funcionamento, a implementação do Place Autocomplete deve usar um token de sessão (de maneira programática ou integrada aos widgets JavaScript, Android ou iOS) por um custo total de US $0,017 por sessão, além de SKUs de dados do Places aplicáveis, dependendo dos campos de dados de local solicitados.

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ê esteja solicitando apenas os campos de dados de lugar necessários.

Implementação programática
Use um token de sessão com suas solicitações de 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, precisa apenas do endereço e local

A API Geocoding pode ser uma opção mais econômica que o Place Details para seu aplicativo, dependendo do desempenho do uso do Place Autocomplete. A eficiência do preenchimento automático de todos os aplicativos varia de acordo com o que os usuários estão inserindo, onde o aplicativo está sendo usado e se as práticas recomendadas de otimização de desempenho foram implementadas.

Para responder à pergunta a seguir, analise quantos caracteres um usuário digita em média antes de selecionar uma previsão do Place Autocomplete no seu aplicativo.

Os usuários selecionam, em média, uma previsão do Place Autocomplete em quatro solicitações ou menos?

Yes

Implementar o Place Autocomplete de forma programática sem tokens de sessão e chamar a API Geocoding na previsão de local selecionada.
A API Geocoding fornece endereços e coordenadas de latitude/longitude por US $0,005 por solicitação. Fazer quatro solicitações de Place Autocomplete - Per Request custa US $0,01132, portanto, o custo total de quatro solicitações, além de uma chamada da Geocoding API sobre a previsão de local selecionada, é de US $0,01632, o que é menor que o preço de preenchimento automático por sessão de US $0,017 por sessão.1

Considere usar as práticas recomendadas de desempenho para ajudar os usuários a conseguir a previsão que estão procurando em ainda menos caracteres.

No

Use o Place Autocomplete com base em sessões com o Place Details.
Como o número médio de solicitações que você espera fazer antes que um usuário selecione uma previsão do Place Autocomplete excede o custo do preço por sessão, a implementação desse recurso deve usar um token de sessão para as solicitações do Place Autocomplete e para as solicitações associadas do Place Details, com um custo total de US $0,017 por 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 que você esteja solicitando apenas os campos de dados básicos.

Implementação programática
Use um token de sessão com suas solicitações de 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. Parâmetro fields que especifica os campos de dados básicos, como endereço e geometria

Considere atrasar solicitações do Place Autocomplete
É possível empregar estratégias como adiar uma solicitação do Place Autocomplete até que o usuário digite os três ou quatro primeiros caracteres para que o aplicativo faça 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 sete caracteres e depois selecionar uma previsão para uma solicitação da API Geocoding, o custo total será de US $0,01632 (4 * US$ 0,00283 Autocomplete por solicitação + US $0,005 Geocoding).1

Se o atraso de solicitações puder receber uma solicitação programática média inferior a quatro, siga as orientações para implementar o Place Autocomplete com a API Geocoding. Observe que o atraso de solicitações pode ser percebido como latência pelo usuário, que pode esperar ver previsões a cada nova pressionamento de tecla.

Considere usar as práticas recomendadas de desempenho para ajudar os usuários a conseguir a previsão que eles procuram em menos caracteres.


  1. Os custos listados aqui estão em USD. Consulte a página Faturamento da Plataforma Google Maps para ver as informações completas.

Práticas recomendadas de desempenho

As diretrizes a seguir descrevem maneiras de otimizar o desempenho do Place Autocomplete:

  • Adicione restrições de país, viés 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 escolhem as preferências de idioma no navegador ou no dispositivo móvel do usuário.
  • Se o Place Autocomplete estiver acompanhado por um mapa, você poderá influenciar o local por janela de visualização do mapa.
  • Em situações em que um usuário não escolhe uma das previsões do Autocomplete, geralmente porque nenhuma dessas previsões é o endereço do resultado desejado, você pode reutilizar a entrada original do usuário para tentar receber resultados mais relevantes:
    • Se você espera que o usuário insira apenas informações de endereço, reutilize a entrada original do usuário em uma chamada para a API Geocoding.
    • Se você espera 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 a viés de local.
    Outros cenários em que é melhor voltar para a API Geocoding incluem:
    • Usuários que inserem endereços de sublocal em países que não sejam a Austrália, a Nova Zelândia ou o Canadá. Por exemplo, o endereço dos EUA "123 Bowdoin St #456, Boston MA, EUA" não é suportado pelo Autocomplete. O Autocomplete é compatível com endereços de sublocal somente na Austrália, na Nova Zelândia e no Canadá. Os formatos de endereço aceitos nesses três países incluem "9/321 Pitt Street, Sydney, New South Wales, Austrália" ou "14/19 Langana Avenue, Browns Bay, Auckland, New Zealand" ou "145-112 Renfrew Dr, Markham, Ontario, Canada".
    • Usuários que inserem endereços com prefixos de trechos de via, como "23-30 29th St, Queens" em Nova York ou "47-380 Kamehameha Hwy, Kaneohe" na ilha de Kauai, no Havaí.

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

O uso da Biblioteca do Places e da API Maps JavaScript precisa estar de acordo com as políticas descritas para a API Places.

Nossos Termos de Serviço

Exiba os logotipos
e as atribuições necessários

Respeite os direitos autorais e a atribuição do Google. Verifique se o logotipo e o aviso de direitos autorais estão visíveis e exiba o logotipo "quot;tecnologia do Google" se você estiver usando dados sem um mapa.

Saiba mais