Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar a Google Maps JavaScript API

Para começar, orientaremos você pelo Console do Desenvolvedor do Google para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar a Google Maps JavaScript API e serviços relacionados
  3. Criar chaves apropriadas
Continuar

Preenchimento automático para endereços e termos de pesquisa

Introdução

O Preenchimento automático é um recurso da biblioteca do Places na Google Maps JavaScript API. É possível usar o preenchimento automático para que os aplicativos ofereçam o comportamento de pesquisa durante a digitação do campo de pesquisa do Google Maps. Quando um usuário começa a digitar um endereço, o preenchimento automático insere o restante.

Primeiros passos

Antes de usar a biblioteca do Places na Google Maps JavaScript API, confira se Google Places API Web Service está ativado no Google API Console, no mesmo projeto que você ajustou para Google Maps JavaScript API.

Para ver a lista de APIs ativadas:

  1. Acesse o Google API Console.
  2. Clique no botão Select a project, selecione o mesmo projeto que você criou para a Google Maps JavaScript API e clique em Open.
  3. Na lista de APIs do Painel, procure a Google Places API Web Service.
  4. Se achar a API na lista, está tudo pronto. Se não, ative-a:
    1. Na parte superior da tela, selecione ENABLE API para exibir a guia Library. É possível também selecionar Library no menu à esquerda.
    2. Procure a Google Places API Web Service e, em seguida, selecione-a na lista de resultados.
    3. Selecione ENABLE. Depois do fim do processo, Google Places API Web Service aparece na lista de APIs no Painel.

Carregamento da biblioteca

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

<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"></script>

Consulte Visão geral das bibliotecas para obter mais informações.

Políticas e limites de uso

Cotas

A Google Places API Web Service e o Place Autocomplete compartilham uma cota de uso, conforme é descrito na documentação de Limites de uso para Google Places API Web Service. Estes limites de uso também se aplicam ao usar Places Library in the Google Maps JavaScript API. O uso diário é calculado como a soma das solicitações do lado do cliente e do lado do servidor

Políticas

O uso de Places Library in the Google Maps JavaScript API deve estar de acordo com as políticas descritas para Google Places API Web Service.

Resumo das classes

A API oferece dois tipos de widgets de preenchimento automático, que podem ser adicionados usando as classes Autocomplete e SearchBox. Além disso, a classe AutocompleteService pode ser usada para recuperar programaticamente resultados de preenchimento automático.

Veja a seguir um resumo das classes disponíveis:

  • Autocomplete adiciona um campo de entrada de texto à página e monitora a digitação de caracteres nesse campo. À medida que o usuário insere texto, o preenchimento automático retorna previsões de locais na forma de uma lista de opções suspensa. Quando o usuário seleciona um local na 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.
  • SearchBox adiciona um campo de entrada de texto à página, de forma semelhante ao preenchimento automático. As diferenças são as seguintes:
    • As principais diferenças estão nos resultados exibidos no seletor: SearchBox fornece uma lista ampliada estendida, que pode incluir locais (da forma definida na Google Places API) e os itens de pesquisa sugeridos. Por exemplo, se o usuário inserir "pizza em são", o seletor poderá incluir a frase "pizza em São Paulo, SP", bem como os nomes de várias pizzarias.
    • SearchBox oferece menos opções de restrição de pesquisa que Autocomplete. No primeiro, é possível direcionar a pesquisa para um determinado LatLngBounds. No segundo, é possível restringir a pesquisa por país e tipos de local determinados, bem como definir os limites.
    Veja os detalhes abaixo.
  • Crie um objeto AutocompleteService para recuperar previsões programaticamente. Chame getPlacePredictions() para recuperar locais correspondentes ou getQueryPredictions() para recuperar locais correspondentes e termos de pesquisa sugeridos. Observação: AutocompleteService não adiciona nenhum controle 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. Veja os detalhes abaixo.

O restante desta página oferece exemplos de casos de uso e detalhes sobre o uso dessas classes.

Como usar o Autocomplete

Este vídeo mostra como usar Autocomplete, incluindo demonstrações e exemplos de código.

Exemplo: preenchimento automático para formulários de endereço

O seu aplicativo inclui um formulário de endereço, como o endereço de entrega para um pedido on-line, um endereço de faturamento de cartão de crédito ou um formulário de reserva de taxi? O preenchimento automático pode ajudar os usuários a informar os detalhes.

A Figura 1 mostra um campo de texto com preenchimento automático e o seletor de previsões de local fornecidas à medida que o usuário digita a consulta de pesquisa:

Um campo de texto com preenchimento automático e o seletor de previsões de local fornecidas à medida que o usuário digita a consulta de pesquisa:
Figura 1: campo de texto com preenchimento automático e o seletor

Quando o usuário seleciona um endereço do seletor, o aplicativo pode preencher o formulário de endereço:

Um formulário de endereço preenchido.
Figura 2: formulário de endereço preenchido

Veja como funciona um formulário de endereço: Ver o exemplo (places-autocomplete-addressform.html).

Continue a ler para ver como adicionar o preenchimento automático a uma página.

Exemplo: preenchimento automático para controles de mapa

O preenchimento automático é útil para solicitar informações dos usuários como parte de um aplicativo de mapas, como mostrado na Figura 3:

Um campo de texto com preenchimento automático mostrando um consulta de pesquisa de cidade parcial e os locais correspondentes.
Figura 3: campo de texto com preenchimento automático e o seletor

Veja como funciona: Ver o exemplo (places-autocomplete-hotelsearch.html).

Continue a ler para ver como adicionar o preenchimento automático a uma página.

Adicionar preenchimento automático para locais e endereços

O Autocomplete cria um campo de entrada de texto na página, fornece previsões de locais em um seletor de IU e retorna detalhes de locais como resposta a uma solicitação getPlace(). Cada entrada no seletor corresponde a um único local (como definido na Google Places API).

O construtor Autocomplete aceita 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 options, que pode conter as propriedades a seguir:
    • Uma matriz de types especifica um tipo explícito ou uma coleção de tipos, como listado nos tipos permitidos abaixo. Se nada for especificado, todos os tipos serão retornados. Em geral, somente um tipo é permitido. A exceção é que é possível combinar com segurança os tipos geocode e establishment, mas observe que isso terá o mesmo efeito que não especificar tipo nenhum. Os tipos permitidos são:
      • geocode instrui o serviço Places a retornar apenas resultados de geocodificação em vez de resultados de empresas.
      • address instrui o serviço Places a retornar apenas resultados de geocodificação com um endereço preciso.
      • establishment instrui o serviço Places a retornar apenas resultados de empresas.
      • a coleção de tipos (regions) instrui o serviço Places a retornar qualquer resultado que corresponda aos seguintes tipos:
        • locality
        • sublocality
        • postal_code
        • country
        • administrative_area1
        • administrative_area2
      • a coleção de tipos (cities) instrui o serviço Places a retornar resultados que correspondam a locality ou administrative_area_3.
    • bounds é um objeto google.maps.LatLngBounds que especifica a área para pesquisa de locais. Os resultados são direcionados, mas não restritos, a locais contidos nesses limites.
    • componentRestrictions é usado para restringir os resultados a grupos específicos. No momento, use componentRestrictions para filtrar por país. Passe o país como um código de país de dois caracteres compatível com ISO 3166-1 Alpha-2.
    • placeIdOnly pode ser usado para instruir o widget de Autocomplete para recuperar IDs de local. Ao chamar getPlace() no objeto Autocomplete, o PlaceResult disponibilizado terá apenas as propriedades place id, types e name definidas. É possível usar o ID de local retornado com chamadas aos serviços de Locais, Geocodificação, Direções ou Matriz de distâncias.

Definir direcionamentos e limites de área de pesquisa para Autocomplete

Os resultados do preenchimento automático podem ser direcionados para favorecer uma localização ou área aproximada das seguintes maneiras:

  • Defina os limites na criação do objeto Autocomplete.
  • Altere os limites de um Autocomplete existente.
  • Defina os limites para a porta de visualização do mapa.
  • Restrinja a pesquisa a um país específico.

Os detalhes estão nas seções abaixo.

Definir os limites na criação do objeto Autocomplete

O exemplo a seguir usa as opções bounds e types para solicitar empresas do tipo "establishment", favorecendo as que estão na área geográfica especificada.

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 options = {
  bounds: defaultBounds,
  types: ['establishment']
};

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

Alterar os limites de um Autocomplete existente

Chame setBounds() para alterar a área de pesquisa em um Autocomplete existente.

// Bias the autocomplete object to the user's geographical location,
// as supplied by the browser's 'navigator.geolocation' object.
function geolocate() {
  if (navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(function(position) {
      var geolocation = {
        lat: position.coords.latitude,
        lng: position.coords.longitude
      };
      var circle = new google.maps.Circle({
        center: geolocation,
        radius: position.coords.accuracy
      });
      autocomplete.setBounds(circle.getBounds());
    });
  }
}

Ver o exemplo (places-autocomplete-addressform.html).

Definir os limites para a porta de visualização do mapa

Use bindTo() para direcionar os resultados para a porta de visualização do mapa, mesmo durante alterações dessa porta.

autocomplete.bindTo('bounds', map);

Ver o exemplo (places-autocomplete.html).

Restringir a pesquisa a um país específico

Use a opção componentRestrictions para restringir a pesquisa com preenchimento automático a um determinado país. O código a seguir restringe os resultados a cidades da França.

var input = document.getElementById('searchTextField');
var options = {
  types: ['(cities)'],
  componentRestrictions: {country: 'fr'}
};

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

O exemplo a seguir permite que o usuário selecione um país e restringe os resultados do preenchimento automático a esse país.

// Set the country restriction based on user input.
// Also center and zoom the map on the given country.
function setAutocompleteCountry() {
  var country = document.getElementById('country').value;
  if (country == 'all') {
    autocomplete.setComponentRestrictions([]);
    map.setCenter({lat: 15, lng: 0});
    map.setZoom(2);
  } else {
    autocomplete.setComponentRestrictions({'country': country});
    map.setCenter(countries[country].center);
    map.setZoom(countries[country].zoom);
  }
  clearResults();
  clearMarkers();
}

Ver o exemplo (places-autocomplete-hotelsearch.html).

Personalizar o marcador de posição para preenchimento automático

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 definir 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 o seu valor de marcador de posição, é necessário processar a localização desse valor no aplicativo. Para obter informações sobre como a Google Maps JavaScript API escolhe o idioma a ser usado, leia a documentação sobre localização.

Obter informações do Autocomplete sobre o local

Quando um usuário seleciona um local nas previsões anexadas ao campo de texto de preenchimento automático, o serviço aciona um evento place_changed. Chame getPlace() no objeto Autocomplete para recuperar um objeto PlaceResult.

Por padrão, o preenchimento automático fornece o endereço completo como uma única linha de texto. O endereço no formato estruturado é útil para formulários de endereço. Use Autocomplete.getPlace() para recuperar todos os detalhes de cada previsão de preenchimento automático, incluindo o endereço estruturado.

Se você usar a opção placeIdOnly, o objeto Autocomplete não obterá detalhes do local, pois o objeto PlaceResult tem apenas as propriedades place_id, types e name definidas.

Para obter detalhes de local, recupere um objeto PlaceResult chamando getPlace() no objeto Autocomplete ao obter o evento place_changed. Você pode então usar a geocodificação para obter as coordenadas de local, ou o serviço Places para obter mais informações no local selecionado.

Para obter mais informações sobre o objeto PlaceResult, consulte a documentação sobre resultados detalhados de local.

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.
  var place = autocomplete.getPlace();

  for (var component in componentForm) {
    document.getElementById(component).value = '';
    document.getElementById(component).disabled = false;
  }

  // Get each component of the address from the place details
  // and fill the corresponding field on the form.
  for (var i = 0; i < place.address_components.length; i++) {
    var addressType = place.address_components[i].types[0];
    if (componentForm[addressType]) {
      var val = place.address_components[i][componentForm[addressType]];
      document.getElementById(addressType).value = val;
    }
  }
}

Ver o exemplo (places-autocomplete-addressform.html).

O SearchBox permite que os usuários executem uma pesquisa geográfica baseada em texto, como "pizza em São Paulo" ou "lojas de sapato perto da rua augusta". Anexe o SearchBox a um campo de texto para que o serviço retorne previsões na forma de um seletor suspenso à medida que o texto é inserido.

SearchBox fornece uma lista ampliada estendida, que pode incluir locais (da forma definida na Google Places API) e os itens de pesquisa sugeridos. Por exemplo, se o usuário inserir "pizza em são", o seletor poderá incluir a frase "pizza em São Paulo, SP", bem como os nomes de várias pizzarias. Quando o usuário seleciona um local na lista, as informações sobre esse local são retornadas ao objeto SearchBox e podem ser recuperadas pelo aplicativo.

O construtor SearchBox aceita 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 conter a propriedade bounds: bounds é um objeto google.maps.LatLngBounds que especifica a área para pesquisa de locais. 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/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 alterar a área de pesquisa para um SearchBox existente, chame setBounds() no objeto SearchBox e passe o objeto LatLngBounds relevante.

Ver o exemplo (places-searchbox.html).

Obter informações de SearchBox

Quando o usuário seleciona um item nas previsões anexadas à caixa de pesquisa, o serviço aciona um evento place_changed. Chame getPlaces() no objeto SearchBox para recuperar uma matriz contendo diversas previsões; cada uma delas é um objeto PlaceResult.

Para obter mais informações sobre o objeto PlaceResult, consulte a documentação sobre resultados detalhados de local.

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

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

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

  // For each place, get the icon, name and location.
  var bounds = new google.maps.LatLngBounds();
  places.forEach(function(place) {
    if (!place.geometry) {
      console.log("Returned place contains no geometry");
      return;
    }
    var 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: map,
      icon: 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 o exemplo (places-searchbox.html).

Aplicar estilo aos widgets de preenchimento automático e SearchBox

Por padrão, os elementos de IU fornecidos por Autocomplete e SearchBox têm estilo para inclusão em um mapa do Google Maps. Ajuste o estilo de acordo com o seu site. As classes CSS a seguir estão disponíveis. Todas as classes listadas a seguir se aplicam aos widgets Autocomplete e SearchBox.

Uma ilustração gráfica 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. A 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 fornecida 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 são um membro dessa classe e da classe pac-item.
pac-item-query Um intervalo 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 baseadas em texto, como "pizza em São Paulo", contém o texto completo da consulta. Por padrão, a cor de pac-item-query é preto. Qualquer texto adicional no pac-item está fora de pac-item-query e herda o estilo de pac-item. Sua 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 é destacado com texto em negrito. Observe que o texto correspondido pode estar em qualquer lugar de pac-item. Esse texto não faz necessariamente parte de pac-item-query e pode estar parcialmente em pac-item-query e no texto restante de pac-item.

Recuperar previsões do serviço de preenchimento automático

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

AutocompleteService expõe os seguintes métodos:

  • getPlacePredictions() retorna previsões de locais. Observação: um "local" pode ser um estabelecimento, uma localização geográfica ou um ponto de interesse proeminente, como definidos pela Places API.
  • getQueryPredictions() retorna uma lista estendida de previsões, que pode incluir locais (da forma definida na Places API) e os itens de pesquisa sugeridos. Por exemplo, se o usuário inserir "pizza em são", o seletor poderá incluir a frase "pizza em São Paulo, SP", bem como os nomes de várias pizzarias.

Os dois métodos acima retornam uma matriz de cinco objetos de previsão no seguinte formato:

  • description é a descrição correspondida.
  • id contém um identificador único que designa esse local. Esse identificador não pode ser usado para recuperar informações sobre esse local, mas pode ser usado para consolidar dados desse local e confirmar sua identidade entre pesquisas separadas. Como IDs podem mudar ocasionalmente, recomendamos que o ID armazenado para um local seja comparado com o ID retornado em solicitações de detalhes posteriores para o mesmo local e atualizado, se necessário. Observação: O campo id está obsoleto e foi substituído por place_id, como descrito na notificação de obsolescência nesta página.
  • 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 é exibida 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 identifica um local de forma exclusiva. Para recuperar informações sobre o local, passe esse identificador no campo placeId de uma solicitação Place Details. Saiba mais sobre como referenciar um local com um ID de local
  • reference contém um token que pode ser usado para consultar o serviço Details no futuro. Esse token pode diferir da referência usada na solicitação ao serviço Details. Recomenda-se que as referências de locais armazenadas sejam atualizadas regularmente. Apesar de esse token identificar o local de forma exclusiva, o inverso não é verdadeiro: um local pode ter vários tokens de referência válidos. Observação: o campo reference está obsoleto e foi substituído por place_id, como descrito na notificação de obsolescência nesta página.
  • 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 de correspondência.

O exemplo abaixo excuta uma solicitação de previsão de consulta para a frase "pizza near" e exibe 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() {
  var displaySuggestions = function(predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK) {
      alert(status);
      return;
    }

    predictions.forEach(function(prediction) {
      var li = document.createElement('li');
      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById('results').appendChild(li);
    });
  };

  var service = new google.maps.places.AutocompleteService();
  service.getQueryPredictions({ input: 'pizza near Syd' }, displaySuggestions);
}
<div id="right-panel">
  <p>Query suggestions for 'pizza near Syd':</p>
  <ul id="results"></ul>
</div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#right-panel {
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}

#right-panel select, #right-panel input {
  font-size: 15px;
}

#right-panel select {
  width: 100%;
}

#right-panel i {
  font-size: 12px;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=places&callback=initService"
    async defer></script>
// 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() {
  var displaySuggestions = function(predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK) {
      alert(status);
      return;
    }

    predictions.forEach(function(prediction) {
      var li = document.createElement('li');
      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById('results').appendChild(li);
    });
  };

  var service = new google.maps.places.AutocompleteService();
  service.getQueryPredictions({ input: 'pizza near Syd' }, displaySuggestions);
}

Ver o exemplo (places-queryprediction.html).

Enviar comentários sobre…

Google Maps JavaScript API
Google Maps JavaScript API
Precisa de ajuda? Acesse nossa página de suporte.