Ocultar
API Javascript do Google Maps v3

Biblioteca do Google Places

  1. Visão geral
  2. Como carregar a biblioteca
  3. Pesquisa de local
    1. Solicitações de pesquisa de local
    2. Solicitações de pesquisa de texto
    3. Respostas de pesquisa
    4. Como acessar resultados adicionais
  4. Detalhes do local
    1. Solicitações de detalhes do local
    2. Respostas de detalhes do local
  5. Preenchimento automático do Google Places
    1. Como adicionar preenchimento automático
    2. Como obter informações de lugares
    3. Como alterar o texto do espaço reservado

Visão geral

As funções da biblioteca JavaScript do Google Places permitem que seu aplicativo faça buscas por locais no Google Places (definidos nesta API como estabelecimentos, locais geográficos ou pontos de interesse destacados) contidos em uma área definida, como, por exemplo, os limites de um mapa ou em torno de um ponto fixo.

Como carregar a biblioteca

O serviço Google Places é uma biblioteca independente, separada do código JavaScript da API do Google Maps principal. Para usar as funções contidas nessa biblioteca, você deve primeiro carregá-la usando o parâmetro libraries no URL de inicialização da API do Google Maps:

<script type="text/javascript" src="http://maps.googleapis.com/maps/api/js?libraries=places&sensor=true_or_false"></script>

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

Pesquisa de locais

Com o serviço Google Places, você pode realizar três tipos de pesquisa:

  • Pesquisa de locais: retorna uma lista de lugares próximos com base na localização do usuário.
  • Pesquisas de texto: retornam uma lista de lugares próximos com base em uma string de pesquisa, por exemplo, "Pizza".
  • Solicitações de detalhes do local: retornam informações mais detalhadas sobre um lugar específico, incluindo a opinião dos usuários.

As informações retornadas podem incluir estabelecimentos (por exemplo, restaurantes, lojas e escritórios), bem como resultados de "geocodificação", que indicam endereços, áreas políticas (por exemplo, cidades e municípios) e outros pontos de interesse.

Solicitações de pesquisa de local

Para encontrar lugares em uma área específica, a biblioteca do Google Places fornece o método search(). Esse método retorna uma matriz de lugares que atendem aos critérios de local, seja um LatLngBounds ou um objeto LatLng que representa um ponto central, e um valor de raio ao redor desse ponto que será pesquisado.

As pesquisas de local são iniciadas com uma chamada para o método PlacesService de search().

service = new google.maps.places.PlacesService(map);
service.search(request, callback);

Esse método tem uma solicitação com os seguintes campos:

  • Pode ser:
    • bounds, que deve ser um objeto google.maps.LatLngBounds que define o retângulo em que a pesquisa será realizada; ou
    • um location e radius; o primeiro tem um objeto google.maps.LatLng e o radius tem um inteiro simples, representando o raio do círculo em metros. O raio máximo permitido é de 50.000 metros.
  • keyword (opcional): um termo a ser associado a todos os campos disponíveis, incluindo, sem limitação, nome, tipo e endereço, bem como a opinião do cliente e outro conteúdo de terceiros.
  • name (opcional): um termo a ser associado aos nomes de lugares. Os resultados serão limitados àqueles que contêm o valor de nome transmitido. Um lugar pode ter nomes adicionais associados a ele, além do nome listado. A API tentará associar o valor name transmitido a todos esses nomes. Como resultado, podem ser retornados lugares cujos nomes listados não coincidem com o termo de pesquisa, mas cujos nomes associados coincidem.
  • rankBy (opcional): especifica a ordem em que os resultados são listados. Os possíveis valores são:
    • google.maps.places.RankBy.PROMINENCE (padrão). Essa opção classifica os resultados com base em sua importância. A classificação favorecerá lugares de destaque dentro do raio definido sobre os lugares próximos que são correspondentes, mas têm menos relevância. A relevância pode ser afetada pela classificação de um local no índice do Google, pelo número de check-ins de seu aplicativo, pela popularidade global e por outros fatores. Quando google.maps.places.RankBy.PROMINENCE é especificado, o parâmetro radius é obrigatório.
    • google.maps.places.RankBy.DISTANCE. Essa opção classifica os resultados em ordem crescente pela distância do location especificado (obrigatório). A classificação dos resultados por distância define o raio de pesquisa fixo de 50 Km. Um raio e/ou limites personalizados não são aceitos com RankBy.DISTANCE. Quando distance é especificado, um ou mais de keyword, name ou types é obrigatório.
  • types (opcional): uma matriz que contém um ou mais dos tipos permitidos relacionados na lista API do Google Places: tipos de local permitidos. O serviço retornará resultados que coincidem com algum dos tipos especificados.

Você também deve transmitir um método de retorno de chamada para search() para manipular o objeto de resultados e uma resposta google.maps.places.PlacesServiceStatus.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      mapTypeId: google.maps.MapTypeId.ROADMAP,
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    types: ['store']
  };

  service = new google.maps.places.PlacesService(map);
  service.search(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

Veja um exemplo (place-search.html)

Solicitações de pesquisa de texto

O serviço de pesquisa de texto do Google Places é um serviço da Web que retorna informações sobre um conjunto de locais com base em uma string, por exemplo, "pizza em New York" ou "lojas de sapato perto de Ottawa". O serviço responde com uma lista de locais que correspondem à string de texto e qualquer polarização de local que tenha sido definida. A resposta da pesquisa incluirá uma lista de locais; você pode enviar uma solicitação de detalhes do local para obter mais informações sobre qualquer local da resposta.

As pesquisas de texto são iniciadas com uma chamada para o método PlacesService de textSearch().

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

Esse método tem uma solicitação com os seguintes campos:

  • query (obrigatório): a string de texto que será pesquisada, por exemplo, "restaurante". O serviço Google Places retornará correspondências candidatas com base nessa string e classificará os resultados com base na relevância observada.
  • Pode ser:
    • bounds, que deve ser um objeto google.maps.LatLngBounds que define o retângulo em que a pesquisa será realizada; ou
    • um location e radius; o primeiro tem um objeto google.maps.LatLng e o radius tem um inteiro simples, representando o raio do círculo em metros. O raio máximo permitido é de 50.000 metros.

Você pode polarizar os resultados para um círculo especificado transmitindo um parâmetro location e um radius. Isso instruirá o serviço Google Places a dar preferência aos resultados nesse círculo; os resultados fora da área definida ainda podem ser exibidos.

Você também deve transmitir um método de retorno de chamada para textSearch() para manipular o objeto de resultados e uma resposta google.maps.places.PlacesServiceStatus.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      mapTypeId: google.maps.MapTypeId.ROADMAP,
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

Respostas de pesquisa

Códigos de status

O objeto de resposta PlacesServiceStatus contém o status da solicitação e pode conter informações de depuração para ajudar você a saber por que a solicitação da pesquisa de local falhou. Os possíveis valores de status são:

  • ERROR: ocorreu um problema ao entrar em contato com os servidores do Google.
  • INVALID_REQUEST: esta solicitação era inválida.
  • OK: a resposta contém um resultado válido.
  • OVER_QUERY_LIMIT: a página da Web ultrapassou sua cota de solicitações.
  • REQUEST_DENIED: a página da Web não pode usar o serviço Google Places.
  • UNKNOWN_ERROR: não foi possível processar a solicitação do serviço Google Places devido a um erro do servidor. A solicitação pode ser concluída se você tentar novamente.
  • ZERO_RESULTS: nenhum resultado foi encontrado para essa solicitação.

Resultados da pesquisa de local

As funções search() e textSearch() retornam uma matriz de objetos PlaceResult. Cada objeto PlaceResult tem as seguintes propriedades:

  • geometry: as informações relacionadas à geometria do local. Isso inclui:
    • location: fornece a latitude e a longitude do local.
    • viewport: define a janela de visualização preferida no mapa durante a visualização desse local.
  • icon: o URL até um recurso da imagem que pode ser usado para representar esse tipo de local.
  • id: contém um identificador exclusivo que indica esse local. Esse identificador não pode ser usado para recuperar informações sobre esse local, mas pode ser usado para consolidar dados sobre esse local e verificar a identidade de um local em pesquisas separadas. Como os IDs podem mudar ocasionalmente, é recomendado que o ID armazenado de um local seja comparado com o ID retornado em solicitações de detalhes posteriores para o mesmo local e atualizado se necessário.
  • name: o nome do local.
  • opening_hours: pode conter as seguintes informações:
    • open_now: é um valor boleano que indica se o local está aberto no horário atual.
  • rating: contém a classificação do local, de 0 a 5, com base na opinião dos usuários. Para obter classificações mais detalhadas, inspecione o conteúdo da matriz aspects[].
  • reference: contém um token que pode ser usado para consultar o serviço de detalhes no futuro. Esse token pode ser diferente da referência usada nas solicitação do serviço de detalhes. É recomendado atualizar regularmente as referências armazenadas no Google Places. Embora esse token identifique com exclusividade o local, o contrário não é válido: um local pode ter muitos tokens de referência válidos.
  • types: uma matriz de tipos para esse local (por exemplo, ["political", "locality"] ou ["restaurant", "establishment"]).
  • vicinity: um endereço simplificado do local, incluindo o nome da rua, o número e a localidade, mas não a província/estado, o código postal ou o país. Por exemplo, o escritório do Google em Sydney, Austrália, tem um valor vicinity de 5/48 Pirrama Road, Pyrmont.
  • formatted_address: é uma string que contém o endereço legível desse local. Geralmente, esse endereço equivale ao "endereço postal". A propriedade formatted_address é retornada somente para uma pesquisa de texto.

Como acessar resultados adicionais

Por padrão, cada pesquisa de local retorna até 20 resultados establishment por consulta. No entanto, cada pesquisa pode retornar 60 resultados, divididos em três páginas. Páginas adicionais estão disponíveis por meio do objeto PlaceSearchPagination. Para acessar as páginas adicionais, você deve capturar o objeto PlaceSearchPagination através de uma função de retorno de chamada. O objeto PlaceSearchPagination é definido como:

  • hasNextPage: uma propriedade boleana que indica se há outros resultados disponíveis. true: quando há uma página adicional de resultados.
  • nextPage(): uma função que retorna o próximo conjunto de resultados. Depois de realizar uma pesquisa, você deve aguardar dois segundos até que a próxima página de resultados seja disponibilizada.

Para ver o próximo conjunto de resultados, chame nextPage. Cada página de resultados deve ser exibida antes da exibição da próxima página de resultados. Cada pesquisa conta como uma única solicitação em seus limites de uso.

O exemplo abaixo demonstra como alterar a função de retorno de chamada para capturar o objeto PlaceSearchPagination para que você possa emitir várias solicitações de pesquisa.

var map;
var service;
var resultList;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      mapTypeId: google.maps.MapTypeId.ROADMAP,
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '5000',
    types: ['store']
  };

  service = new google.maps.places.PlacesService(map);

  service.nearbySearch(request, function(status, results, pagination) {
    if (status != google.maps.places.PlacesServiceStatus.OK) {
     return;
    }
    resultList.addPlaces(results);
    if (pagination.hasNextPage) {
      resultList.button.onClick = pagination.nextPage;
    }
  });
}

Detalhes do local

Além de fornecer uma lista de locais em uma área, o serviço Google Places também pode retornar informações detalhadas sobre um local específico. Assim que um local é retornado em uma resposta da pesquisa de local, a propriedade reference pode ser usada para solicitar detalhes adicionais sobre esse local, como, por exemplo, endereço completo, número de telefone, avaliação e opinião dos usuários etc.

Solicitações de detalhes do local

Os detalhes do local são solicitados com uma chamada para o método getDetails() do serviço.

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

Esse método possui uma solicitação, que contém o valor reference do local desejado.

Também tem um método de retorno de chamada, que precisa manipular o código de status transmitido na resposta google.maps.places.PlacesServiceStatus, bem como o objeto google.maps.places.PlaceResult.

var request = {
  reference: 'CnRkAAAAGnBVNFDeQoOQHzgdOpOqJNV7K9-c5IQrWFUYD9TNhUmz5-aHhfqyKH0zmAcUlkqVCrpaKcV8ZjGQKzB6GXxtzUYcP-muHafGsmW-1CwjTPBCmK43AZpAwW0FRtQDQADj3H2bzwwHVIXlQAiccm7r4xIQmjt_Oqm2FejWpBxLWs3L_RoUbharABi5FMnKnzmRL2TGju6UA4k'
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

Veja um exemplo (place-details.html)

Respostas de detalhes do local

Códigos de status

O objeto de resposta PlacesServiceStatus contém o status da solicitação e pode conter informações de depuração para ajudar você a saber por que a solicitação de detalhes do local falhou. Os possíveis valores de status são:

  • ERROR: ocorreu um problema ao entrar em contato com os servidores do Google.
  • INVALID_REQUEST: esta solicitação era inválida.
  • OK: a resposta contém um resultado válido.
  • OVER_QUERY_LIMIT: a página da Web ultrapassou sua cota de solicitações.
  • NOT_FOUND: o local referenciado não foi encontrado no banco de dados do Google Places.
  • REQUEST_DENIED: a página da Web não pode usar o serviço Google Places.
  • UNKNOWN_ERROR: não foi possível processar a solicitação do serviço Google Places devido a um erro do servidor. A solicitação pode ser concluída se você tentar novamente.
  • ZERO_RESULTS: nenhum resultado foi encontrado para essa solicitação.

Resultados de detalhes do local

Uma chamada getDetails() bem-sucedida retorna um objeto PlaceResult com as seguintes propriedades:

  • address_components: a coleção de componentes de endereço desse local do Google Places. Consulte a seção Tipos de componente de endereço do serviço de geocodificação para obter mais detalhes.
  • formatted_address: o endereço completo do local.
  • formatted_phone_number: o número de telefone do local, formatado de acordo com a convenção regional do número.
  • geometry: as informações relacionadas à geometria do local. Isso inclui:
    • location: fornece a latitude e a longitude do local.
    • viewport: define a janela de visualização preferida no mapa durante a visualização desse local.
  • html_attributions: texto de atribuição a ser exibido para esse resultado de local.
  • icon: o URL até um recurso da imagem que pode ser usado para representar esse tipo de local.
  • id: contém um identificador exclusivo que indica esse local. Esse identificador não pode ser usado para recuperar informações sobre esse local, mas pode ser usado para consolidar dados sobre esse local e verificar a identidade de um local em pesquisas separadas. Como os IDs podem mudar ocasionalmente, é recomendado que o ID armazenado de um local seja comparado com o ID retornado em solicitações de detalhes posteriores para o mesmo local e atualizado se necessário.
  • international_phone_number: contém o número de telefone do local em formato internacional. O formato internacional inclui o código do país e tem como prefixo o sinal de adição (+). Por exemplo, o international_phone_number do escritório do Google em Sydney, Austrália, é +61 2 9374 4000.
  • name: o nome do local.
  • utc_offset: contém o número de minutos em que o fuso horário atual deste local é desviado em relação a UTC. Por exemplo, para locais em Sydney, Austrália, durante o horário de verão, seria 660 (+11 horas de UTC) e, para lugares na Califórnia fora do horário de verão, seria -480 (-8 horas de UTC).
  • opening_hours: pode conter as seguintes informações:
    • open_now: é um valor boleano que indica se o local está aberto no horário atual.
    • periods[]: é uma matriz de períodos de funcionamento que abrangem sete dias, a partir de domingo, em ordem cronológica. Cada período pode conter:
      • open: um par de objetos de dia e hora descrevendo quando o local abre:
        • day: um número de 0 a 6 correspondente aos dias da semana, a partir de domingo. Por exemplo, 2 significa terça-feira.
        • time: pode conter uma hora do dia no formato hhmm de 24 horas (os valores estão no intervalo de 0000 a 2359). O time será relatado no fuso horário do local.
      • close: contém um par de objetos de dia e hora que descrevem quando o local fecha.
  • rating: a classificação do local, de 0 a 5, com base na opinião dos usuários. Para obter classificações mais detalhadas, inspecione o conteúdo da matriz aspects[].
  • reference: contém um token que pode ser usado para consultar o serviço de detalhes no futuro. Esse token pode ser diferente da referência usada nas solicitação do serviço de detalhes. É recomendado atualizar regularmente as referências armazenadas no Google Places. Embora esse token identifique com exclusividade o local, o contrário não é válido: um local pode ter muitos tokens de referência válidos.
  • reviews: uma matriz de até cinco opiniões. Cada opinião consiste em vários componentes:
    • aspects[]: uma matriz de objetos PlaceAspectRating, cada um fornecendo uma classificação de um único atributo do estabelecimento. O primeiro objeto da matriz é considerado o aspecto principal. Cada PlaceAspectRating é definido como:
      • type: o nome do aspecto que está sendo classificado. Por exemplo, atmosfera, serviço, alimento, dados gerais etc.
      • rating: a classificação do usuário para esse aspecto específico, de 0 a 3.
    • author_name: o nome do usuário que enviou a opinião. As opiniões anônimas são atribuídas a "Um usuário do Google". Se um parâmetro de idioma tiver sido definido, a frase "Um usuário do Google" retornará uma string localizada.
    • author_url: o URL para o perfil do Google+ dos usuários, se disponível.
    • text: contém a opinião do usuário. Ao avaliar um local com o Google Places, os comentários de texto são considerados opcionais; portanto, esse campo pode ficar vazio.
    • time: a hora em que a opinião foi enviada, medida no número de segundos desde meia-noite de 1º de janeiro de 1970 UTC.
  • types: uma matriz de tipos para esse local (por exemplo, ["political", "locality"] ou ["restaurant", "establishment"]).
  • url: URL da página do Google Places associada.
  • vicinity: um endereço simplificado do local, incluindo o nome da rua, o número e a localidade, mas não a província/estado, o código postal ou o país. Por exemplo, o escritório do Google em Sydney, Austrália, tem um valor vicinity de 5/48 Pirrama Road, Pyrmont. A propriedade vicinity só é retornada para uma pesquisa de local.
  • website: lista o website oficial desse local, como, por exemplo, a página inicial de uma empresa.

Classificações multidimensionais talvez não estejam disponíveis para todos os locais. Se houver poucas opiniões, a resposta de detalhes incluirá uma classificação legada em uma escala de 0 a 5 (se disponível) ou nenhuma classificação.

Preenchimento automático do Google Places

O recurso "Preenchimento automático do Google Places" está associado a um campo de texto em sua página da Web e monitora a entrada de caracteres nesse campo. Conforme o texto é inserido, o preenchimento automático retorna previsões de locais para o aplicativo na forma de uma lista suspensa.

Quando o usuário seleciona um local na lista, informações sobre o local são retornadas para o objeto de preenchimento automático e podem ser recuperadas por seu aplicativo.

Como adicionar preenchimento automático

O construtor do preenchimento automático tem dois argumentos:

  • Um elemento HTML input do tipo text. Este é o campo de entrada que o serviço de preenchimento automático monitora e onde inclui os resultados.
  • Um argumento options, que pode conter:
    • types, que pode especificar um dos dois tipos explícitos ou uma das duas coleções de tipo. Os tipos permitidos são:
      • geocode: instrui o serviço de local a retornar somente resultados de geocodificação (endereço).
      • establishment: instrui o serviço de local a retornar somente resultados da empresa.
      • a coleção de tipos (regions) instrui o serviço de local a retornar qualquer resultado correspondente aos seguintes tipos:
        • locality
        • sublocality
        • postal_code
        • country
        • administrative_area1
        • administrative_area2
      • a coleção de tipos (cities) instrui o serviço de local a retornar resultados correspondentes a locality ou administrative_area3.
    • bounds é um objeto google.maps.LatLngBounds que especifica a área em que os locais serão procurados. Os resultados são polarizados, mas não se limitam a locais contidos nesses limites.
    • componentRestrictions pode ser usado para restringir resultados a grupos específicos. Atualmente, você pode usar componentRestrictions para filtrar por país. O país deve ser transmitido como um código de país de dois caracteres compatível com ISO 3166-1 Alpha-2.

O exemplo abaixo usa os limites e o parâmetro de tipos para polarizar os resultados para empresas dentro da á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);

O exemplo abaixo restringe sua solicitação de preenchimento automático 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);

Assim que o controle é criado, ele monitora a entrada no campo de texto especificado e retorna sugestões de local à medida que o texto é inserido nesse campo.

Como alterar a área de pesquisa

Para alterar a área em que o preenchimento automático procura locais, chame setBounds() no objeto de preenchimento automático.

autocomplete.setBounds(bounds);

Para polarizar os resultados para a janela de visualização do mapa, mesmo que essa janela de visualização seja alterada, use a função bindTo() do objeto de preenchimento automático.

autocomplete.bindTo('bounds', map);

Veja um exemplo (places-autocomplete.html)

Como obter informações do local

Quando o usuário seleciona um local entre as sugestões relacionadas ao campo de texto, o serviço aciona um evento place_changed. O serviço de local também retorna um objeto PlaceResult, que pode ser acessado chamando getPlace() no objeto de preenchimento automático.

google.maps.event.addListener(autocomplete, 'place_changed', function() {
  var place = autocomplete.getPlace();
  if (place.geometry.viewport) {
    map.fitBounds(place.geometry.viewport);
  } else {
    map.setCenter(place.geometry.location);
    map.setZoom(17);
  }
  var image = new google.maps.MarkerImage(
      place.icon, new google.maps.Size(71, 71),
      new google.maps.Point(0, 0), new google.maps.Point(17, 34),
      new google.maps.Size(35, 35));
  marker.setIcon(image);
  marker.setPosition(place.geometry.location);

  infowindow.setContent(place.name);
  infowindow.open(map, marker);
});

Para obter mais informações sobre o objeto PlaceResult, consulte a seção Resultados de detalhes do local desta documentação.

Como alterar o texto do espaço reservado

Por padrão, o campo de texto criado pelo serviço de preenchimento automático contém um texto de espaço reservado padrão. Para modificar o texto, defina o atributo placeholder no elemento input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

O texto padrão do espaço reservado é localizado automaticamente; ao especificar um valor para o espaço reservado, qualquer localização desse valor deverá ser manipulada por seu aplicativo. Para obter informações sobre como a API do Google Maps escolhe o idioma a ser usado, leia Localização na API do Google Maps v3.