Biblioteca Places

  1. Visão geral
  2. Carregamento da biblioteca
  3. Place Searches
    1. Solicitações Nearby Search
    2. Solicitações Text Search
    3. Radar Search
    4. Respostas da pesquisa
    5. Acesso a resultados adicionais
  4. Place Details
    1. Solicitações de Place Details
    2. Respostas de Place Details
  5. Referência a um local com um ID de local
  6. Place Photos

Visão geral

As funções da biblioteca JavaScript do Google Places permitem que o aplicativo pesquise locais (definidos nessa API como estabelecimentos, localizações geográficas ou pontos de interesse proeminentes) contidos em uma área definida, como os limites de um mapa ou a vizinhança de um ponto fixo.

A Google Places API disponibiliza um recurso de preenchimento automático que pode ser usado 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. Para obter mais informações, consulte a documentação de preenchimento automático.

Carregamento da biblioteca

O serviço Places é uma biblioteca independente, separada do código JavaScript principal da Maps 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.

Requisitos do logotipo

Se o aplicativo exibir dados da Google Places API em um mapa, ele deverá ser fornecido pela Google.

Se o aplicativo exibir dados da Google Places API em uma página ou vista que não exibe também um Google Map, será necessário exibir um logotipo "Powered by Google" com esses dados. Por exemplo, se o aplicativo exibir uma lista de locais em uma guia e um Google Map com esses locais em outra guia, a primeira guia deverá exibir o logotipo "Powered by Google".

Para uso com segundo plano branco Para uso com segundo plano diferente de branco

O arquivo ZIP a seguir contém o logotipo "Powered by Google" nos tamanhos corretos para aplicativos para computador, Android e iOS. Não é permitido redimensionar nem modificar esses logotipos de nenhuma forma.

Download: powered-by-google.zip

Place Searches

O serviço Searches permite executar quatro tipos de pesquisas:

  • Nearby Search retorna uma lista de locais próximos de acordo com a localização do usuário.
  • Text Search retorna uma lista de locais próximos de acordo com uma string de pesquisa, por exemplo, "Pizza".
  • Radar Search retorna uma lista grande de locais dentro de um raio de pesquisa especificado, com menos detalhes que Nearby Search e Text Search.
  • Solicitações de Place Details retornam informações mais detalhadas sobre um local específico, incluindo avaliações de usuários.

As informações retornadas podem incluir estabelecimentos, como restaurantes, lojas e escritórios, e resultados de "geocode" que indicam endereços, áreas políticas como áreas urbanas e cidades e outros pontos de interesse.

Solicitações Nearby Search

Uma Nearby Search permite pesquisar locais em uma área especificada por palavra-chave ou tipo. Uma Nearby Search deve sempre incluir uma localização, que pode ser especificada de duas formas:

  • um LatLngBounds.
  • uma área circular definida como a combinação da propriedade location (que especifica o centro de um círculo como um objeto LatLng) e um raio medido em metros.

Uma pesquisa Places Nearby é iniciada com uma chamada ao método nearbySearch() de PlacesService, que retorna uma matriz de objetos PlaceResult. Observe que o método nearbySearch() substitui o método search() a partir da versão 3.9.

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

Esse método recebe solicitações com os seguintes campos:

  • Uma das seguintes opções:
    • bounds, que deve ser um objeto google.maps.LatLngBounds definindo a área de pesquisa retangular, ou
    • location e radius; o primeiro recebe um objeto google.maps.LatLng e o segundo recebe um inteiro simples que representa o raio do círculo em metros. O raio máximo permitido é de 50.000 metros.
  • keyword (opcional) — termo a ser correspondido com todos os campos disponíveis, incluindo, entre outros, nome, tipo e endereço, bem como avaliações de clientes e conteúdo de terceiros.
  • minPriceLevel e maxPriceLevel (opcional) — restringe os resultados apenas a locais dentro da faixa especificada. Valores válidos estão no intervalo de 0 (mais barato) a 4 (mais caro), inclusive.
  • name (opcional) — um termo a ser correspondido com os nomes dos locais. Os resultados serão restritos aos que contêm os valores de name passados. Observe que um local pode ter nomes adicionais associados a ele, além do nome listado. A API tenta corresponder o valor de name passado com todos esses nomes. Como resultado, é possível o retorno de locais em que o termo de pesquisa não corresponde aos nomes listados, mas corresponde aos nomes associados.
  • openNow (opcional) — um valor booleano indicando que o serviço Places deve retornar somente os locais que estão no horário de funcionamento no momento em que a consulta é enviada. Locais que não especificam horário de funcionamento no banco de dados do Google Places não serão retornados se esse parâmetro for incluído na consulta. A definição de openNow como false não tem efeito.
  • rankBy (opcional) — Especifica a ordem em que os resultados são listados. Os valores possíveis são:
    • google.maps.places.RankBy.PROMINENCE (padrão). Essa opção classifica os resultados com base na importância. Dos locais dentro do raio especificado, a classificação priorizará os locais proeminentes em relação aos menos proeminentes. A proeminência pode ser afetada pela classificação de um local no índice do Google, 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 de distância a partir do parâmetro location especificado (obrigatório). Não é possível usar raio e/ou limites personalizados juntamente com RankBy.DISTANCE. Quando RankBy.DISTANCE é especificado, um ou mais keyword, name ou types são obrigatórios.
  • types (opcional) — uma matriz contendo um ou mais dos tipos suportados contidos na lista Google Places API: Tipos de local suportados. O serviço retornará os resultados que correspondem a qualquer dos tipos especificados.

Além disso, é necessário passar um método de retorno de chamada para nearbySearch() para tratar o objeto de resultados e a resposta de 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'), {
      center: pyrmont,
      zoom: 15
    });

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

  service = new google.maps.places.PlacesService(map);
  service.nearbySearch(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]);
    }
  }
}

Ver o exemplo (place-search.html)

Solicitações Text Search

O serviço Text Search do Google Places é um serviço web que retorna informações sobre um conjunto de locais com base em uma string, como, por exemplo, "pizza em Nova Iorque" ou "loja de sapatos perto de Ottawa". O serviço responde com uma lista de locais correspondentes à string de texto e a todos os direcionamentos de localização definidos. A resposta da pesquisa inclui uma lista de locais. É possível enviar uma solicitação de Place Details para obter mais informações sobre qualquer um dos locais dessa lista.

Text Searches são iniciadas com uma chamada para o método textSearch() de PlacesService.

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

Esse método recebe solicitações com os seguintes campos:

  • query (obrigatório) a string de texto a pesquisar, por exemplo, "restaurante". O serviço Places retorna as correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância percebida.
  • Opcionalmente:
    • openNow — um valor booleano indicando que o serviço Places deve retornar somente os locais que estão no horário de funcionamento no momento em que a consulta é enviada. Locais que não especificam horário de funcionamento no banco de dados do Google Places não serão retornados se esse parâmetro for incluído na consulta. A definição de openNow como false não tem efeito.
    • minPriceLevel e maxPriceLevel — restringe os resultados apenas a locais dentro do nível de preço especificado. Valores válidos estão no intervalo de 0 (mais barato) a 4 (mais caro), inclusive.
    • Uma das seguintes opções:
      • bounds — um objeto google.maps.LatLngBounds definindo o retângulo para a pesquisa, ou
      • location e radius — é possível direcionar os resultados para um círculo especificando passando parâmetros location e radius. Isso instruirá o serviço Places a exibir preferencialmente os resultados dentro desse círculo. Os resultados fora da área definida ainda poderão ser exibidos. location recebe um objeto google.maps.LatLng e radius recebe um inteiro simples que representa o raio do círculo em metros. O raio máximo permitido é de 50.000 metros.
    • types — uma matriz contendo um ou mais dos tipos suportados contidos na lista Google Places API: Tipos de local suportados. O serviço retornará os resultados que correspondem a qualquer dos tipos especificados.

Além disso, é necessário passar um método de retorno de chamada para textSearch() para tratar o objeto de resultados e a resposta de 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'), {
      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]);
    }
  }
}

Solicitações Radar Search

Uma Radar Search permite pesquisas de locais dentro de um raio específico por palavra-chave, tipo ou nome. A Radar Search retorna mais resultados que Nearby Search ou Text Search. No entanto, os resultados contêm menos campos. É possível chamar PlacesService.getDetails() para obter mais informações sobre qualquer um dos locais na resposta.

Os objetos do PlaceResult retornados por radarSearch() incluem apenas as seguintes propriedades:

  • geometry.location
  • place_id
  • reference (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.)

Uma pesquisa Radar Search é iniciada com uma chamada ao método radarSearch() de PlacesService, que retorna uma matriz de até 200 objetos PlaceResult.

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

Esse método recebe solicitações com os seguintes campos:

  • Uma das seguintes opções:
    • bounds, que deve ser um objeto google.maps.LatLngBounds definindo a área de pesquisa retangular, ou
    • location e radius; o primeiro recebe um objeto google.maps.LatLng e o segundo recebe um inteiro simples que representa o raio do círculo em metros. O raio máximo permitido é de 50.000 metros.
  • Pelo menos um dos seguintes parâmetros:
    • keyword (opcional) — termo a ser correspondido com todos os campos disponíveis, incluindo, entre outros, nome, tipo e endereço, bem como avaliações de clientes e conteúdo de terceiros.
    • name (opcional) — um termo a ser correspondido com os nomes dos locais. Os resultados serão restritos aos que contêm os valores de name passados. Observe que um local pode ter nomes adicionais associados a ele, além do nome listado. A API tenta corresponder o valor de name passado com todos esses nomes. Como resultado, é possível o retorno de locais em que o termo de pesquisa não corresponde aos nomes listados, mas corresponde aos nomes associados.
    • types (opcional) — uma matriz contendo um ou mais dos tipos suportados contidos na lista Google Places API: Tipos de local suportados. O serviço retornará os resultados que correspondem a qualquer dos tipos especificados.
  • Opcionalmente:
    • minPriceLevel e maxPriceLevel (opcional) — restringe os resultados apenas a locais dentro do nível de preço especificado. Valores válidos estão no intervalo de 0 (mais barato) a 4 (mais caro), inclusive.
    • openNow — um valor booleano indicando que o serviço Places deve retornar somente os locais que estão no horário de funcionamento no momento em que a consulta é enviada. Locais que não especificam horário de funcionamento no banco de dados do Google Places não serão retornados se esse parâmetro for incluído na consulta. A definição de openNow como false não tem efeito.

Além disso, é necessário passar um método de retorno de chamada para radarSearch() para tratar o objeto PlaceResults e google.maps.places.PlacesServiceStatus.

var map;
var infoWindow;
var service;

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.867, lng: 151.206},
    zoom: 15,
    styles: [{
      stylers: [{ visibility: 'simplified' }]
    }, {
      elementType: 'labels',
      stylers: [{ visibility: 'off' }]
    }]
  });

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

  // The idle event is a debounced event, so we can query & listen without
  // throwing too many requests at the server.
  map.addListener('idle', performSearch);
}

function performSearch() {
  var request = {
    bounds: map.getBounds(),
    keyword: 'best view'
  };
  service.radarSearch(request, callback);
}

function callback(results, status) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    console.error(status);
    return;
  }
  for (var i = 0, result; result = results[i]; i++) {
    addMarker(result);
  }
}

function addMarker(place) {
  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    icon: {
      url: 'http://maps.gstatic.com/mapfiles/circle.png',
      anchor: new google.maps.Point(10, 10),
      scaledSize: new google.maps.Size(10, 17)
    }
  });

  google.maps.event.addListener(marker, 'click', function() {
    service.getDetails(place, function(result, status) {
      if (status !== google.maps.places.PlacesServiceStatus.OK) {
        console.error(status);
        return;
      }
      infoWindow.setContent(result.name);
      infoWindow.open(map, marker);
    });
  });
}

Ver o exemplo (place-radar-search.html).

Respostas da 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 a rastrear o motivo de falhas de solicitação de local. Os valores de status possíveis são:

  • ERROR: houve um problema no contato com os servidores da Google.
  • INVALID_REQUEST: esta solicitação é inválida.
  • OK: a resposta contém um resultado válido.
  • OVER_QUERY_LIMIT: a página excedeu sua cota de solicitações.
  • REQUEST_DENIED: a página não tem permissão para usar PlacesService.
  • UNKNOWN_ERROR: a solicitação de PlacesService não foi processada devido a um erro de servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.
  • ZERO_RESULTS: nenhum resultado foi encontrado para a solicitação.

Resultados de Place Search

As funções nearbySearch() e textSearch() retornam uma matriz de objetos PlaceResult. A função radarSearch() retorna um subconjunto dos campos no PlaceResult, como descrito acima.

Cada objeto PlaceResult pode incluir as seguintes propriedades:

  • formatted_address é uma string contendo o endereço do local legível por humanos. Frequentemente esse endereço é equivalente ao "endereço postal". A propriedade formatted_address só é retornada para uma Text Search.
  • geometry: informações relacionadas à geometria do local. Essas informações incluem:
    • location, que fornece a latitude e a longitude do local.
    • viewport, que define a porta de visualização preferencial no mapa ao visualizar o local.
  • html_attributions: uma matriz de atribuições que devem ser exibidas juntamente com os resultados da pesquisa. Cada entrada do matriz contém o texto HTML para uma única atribuição. Observação: esta é uma agregação de todas as atribuições para toda a resposta da pesquisa. Portanto, todos os objetos PlaceResult na resposta contêm listas de atribuição idênticas.
  • icon: URL de um recurso de imagem que pode ser usado para representar o tipo do local.
  • 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, recomenda-se que o ID armazenado para um local seja comparado com o ID retornado em solicitações de detalhes posteriores para o mesmo local e seja 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.
  • name: o nome do local.
  • opening_hours pode conter as seguintes informações:
    • open_now é um valor booleano indicando se o local está aberto no momento.
  • 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.
  • rating contém a classificação do local, de 0.0 a 5.0, com base em avaliações agregadas de usuários.
  • 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.
  • types: uma matriz de tipos para este local (por exemplo, ["política", "localidade"] ou ["restaurante", "estabelecimento"]).
  • vicinity: um endereço simplificado para o local, incluindo o nome da rua, o número da rua e a localidade, mas não província/estado, código postal ou país. Por exemplo, o escritório da Google em Sidnei, Austrália, tem um valor de vicinity de 5/48 Pirrama Road, Pyrmont.

Acesso a resultados adicionais

Por padrão, cada pesquisa de local retorna até 20 resultados por consulta. No entanto, cada pesquisa pode retornar até 60 resultados, divididos em três páginas. Páginas adicionais são disponibilizadas pelo objeto PlaceSearchPagination. Para acessar páginas adicionais, é necessário capturar o objeto PlaceSearchPagination por meio de uma função de retorno de chamada. O objeto PlaceSearchPagination é definido como:

  • hasNextPage, uma propriedade booleana que indica a disponibilidade de mais resultados. true quando existe uma página de resultados adicionais.
  • nextPage(), uma função que retorna o próximo conjunto de resultados. Após a execução de uma pesquisa, é necessário aguardar dois segundos antes que a próxima página de resultados fique disponível.

Para ver o próximo conjunto de resultados, chame nextPage. Cada página de resultados deve ser exibida antes que a próxima possa ser exibida. Observe que cada pesquisa conta como uma única solicitação em relação aos seus limites de uso.

O exemplo a seguir demonstra como alterar a função de retorno de chamada para capturar o objeto PlaceSearchPagination, permitindo enviar várias solicitações de pesquisa.

var map;

function initMap() {
  var pyrmont = {lat: -33.866, lng: 151.196};

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

  var service = new google.maps.places.PlacesService(map);
  service.nearbySearch({
    location: pyrmont,
    radius: 500,
    types: ['store']
  }, processResults);
}

function processResults(results, status, pagination) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    return;
  } else {
    createMarkers(results);

    if (pagination.hasNextPage) {
      var moreButton = document.getElementById('more');

      moreButton.disabled = false;

      moreButton.addEventListener('click', function() {
        moreButton.disabled = true;
        pagination.nextPage();
      });
    }
  }
}

function createMarkers(places) {
  var bounds = new google.maps.LatLngBounds();
  var placesList = document.getElementById('places');

  for (var i = 0, place; place = places[i]; i++) {
    var image = {
      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)
    };

    var marker = new google.maps.Marker({
      map: map,
      icon: image,
      title: place.name,
      position: place.geometry.location
    });

    placesList.innerHTML += '<li>' + place.name + '</li>';

    bounds.extend(place.geometry.location);
  }
  map.fitBounds(bounds);
}

Ver o exemplo (place-search-pagination.html).

Place Details

Além de fornecer uma lista de locais dentro de uma área, o serviço Places também pode retornar informações detalhadas sobre um local específico. Depois que um local é retornado em uma resposta de pesquisa de local, seu ID de local pode ser usado para solicitar detalhes adicionais, como endereço completo, número do telefone, classificações e avaliações de usuários etc. (Também é possível usar o campo reference de um local para recuperar os detalhes do local, mas esse campo está obsoleto e foi substituído pelo ID do local, como descrito na notificação de obsolescência nesta página.)

Solicitações de Place Details

Place Details são solicitados com uma chamada ao método getDetails() do serviço.

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

Esse método recebe uma solicitação com o placeId ou a reference do local. O campo reference está obsoleto e foi substituído por placeId, como descrito na notificação de obsolescência nesta página. Saiba mais sobre como referenciar um local com um ID de local.

O método também recebe um método de retorno de chamada, que precisa tratar o código de status passado na resposta google.maps.places.PlacesServiceStatus, bem como o objeto google.maps.places.PlaceResult.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4'
};

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

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

Ver o exemplo (place-details.html)

Respostas de Place Details

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 a rastrear o motivo de falhas de solicitação de Place Details. Os valores de status possíveis são:

  • ERROR: houve um problema no contato com os servidores da Google.
  • INVALID_REQUEST: esta solicitação é inválida.
  • OK: a resposta contém um resultado válido.
  • OVER_QUERY_LIMIT: a página excedeu sua cota de solicitações.
  • NOT_FOUND: o local referenciado não foi encontrado no banco de dados do Places.
  • REQUEST_DENIED: a página não tem permissão para usar PlacesService.
  • UNKNOWN_ERROR: a solicitação de PlacesService não foi processada devido a um erro de servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.
  • ZERO_RESULTS: nenhum resultado foi encontrado para a solicitação.

Resultados de Place Details

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

  • address_components: a coleção de componentes de endereço para a localização desse local. Consulte a seção Address Component Types do serviço Geocoding 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: informações relacionadas à geometria do local. Essas informações incluem:
    • location, que fornece a latitude e a longitude do local.
    • viewport, que define a porta de visualização preferencial no mapa ao visualizar o local.
  • html_attributions: texto de atribuição a ser exibido para esse resultado de local.
  • icon: URL de um recurso de imagem que pode ser usado para representar o tipo do local.
  • 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, recomenda-se que o ID armazenado para um local seja comparado com o ID retornado em solicitações de detalhes posteriores para o mesmo local e seja 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.
  • 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 é prefixado pelo sinal de mais (+). Por exemplo, o international_phone_number do escritório da Google em Sidnei, Austrália, é +61 2 9374 4000.
  • name: o nome do local.
  • utc_offset contém o número de minutos de diferença entre o fuso horário do local e o UTC. Por exemplo, para locais em Sidnei, Austrália, durante o horário de verão, esse valor seria de 660 (+11 horas em relação ao UTC) e, para locais na Califórnia, fora do horário de verão, seria de -480 (-8 horas em relação ao UTC).
  • opening_hours contém as seguintes informações:
    • open_now é um valor booleano indicando se o local está aberto no momento.
    • periods[] é uma matriz de períodos de funcionamento contendo sete dias, iniciando em domingo, em ordem cronológica. Cada período contém:
      • open, que contém um par de objetos de dia e hora descrevendo quando o local abre:
        • day é um número de 0 a 6, correspondendo aos dias da semana, iniciando em domingo. Por exemplo, 2 significa terça-feira.
        • time pode conter uma hora do dia no formato hhmm de 24 horas (valores na faixa de 0000 a 2359). time será informado no fuso horário do local.
      • close pode conter um par de objetos de dia e hora descrevendo quando o local fecha. Observação: se um local estiver sempre aberto, a seção close estará ausente da resposta. Os aplicativos podem confiar que sempre aberto será representado como um período open contendo day com valor 0 e time com valor 0000, e sem close.
    • weekday_text é uma matriz de sete strings representando os horários de funcionamento formatados para cada dia da semana. Se um parâmetro language for especificado na solicitação de Place Details, o serviço Places formatará e localizará os horários de funcionamento apropriadamente para aquele idioma. A ordem dos elementos nessa matriz depende do parâmetro language. Alguns idiomas iniciam a semana na segunda-feira e outros iniciam no domingo.
  • permanently_closed: um sinalizador booleano indicando se o local foi fechado permanentemente (valor true). Se o local não estiver permanentemente fechado, o sinalizador estará ausente da resposta.
  • photos[]: uma matriz de objetos PlacePhoto. Um PlacePhoto pode ser usado para obter uma foto com o método getUrl() ou você pode examinar o objeto procurando os seguintes valores:
    • height: a altura máxima da imagem em pixels.
    • width: a largura máxima da imagem em pixels.
    • html_attributions: texto de atribuição a ser exibido para essa foto do local.
  • place_id: um identificador textual que identifica um local de forma exclusiva e pode ser usado para recuperar informações sobre o local mediante uma solicitação de Place Details. Saiba mais sobre como referenciar um local com um ID de local.
  • rating: a classificação do local, de 0.0 a 5.0, com base em avaliações agregadas de usuários.
  • 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.
  • reviews é uma matriz de até cinco avaliações. Cada avaliação consiste em vários componentes:
    • aspects[] contém uma coleção de objetos PlaceAspectRating, cada um dos quais fornece uma classificação de um único atributo do estabelecimento. O primeiro objeto na matriz é considerado o aspecto principal. Cada PlaceSearchPagination é definido como:
      • type é o nome do aspecto que está sendo avaliado. Os seguintes tipos são permitidos: appeal, atmosphere, decor, facilities, food, overall, quality e service.
      • rating é a classificação de usuário para esse aspecto em particular, de 0 a 3.
    • author_name é o nome do usuário que enviou a avaliação. Avaliações anônimas são atribuídas a "Um usuário do Google". Se o parâmetro de idioma foi definido, a frase "Um usuário do Google" retornará uma string localizada.
    • author_url é o URL para o perfil Google+ do usuário, se disponível.
    • language é um código de idioma IETF indicando o idioma usado na avaliação do usuário. Esse campo contém somente a tag do idioma principal e não a tag secundária indicando o país ou a região. Por exemplo, todas as avaliações em inglês são marcadas como "en", e não "en-AU" ou "en-UK", e assim por diante.
    • rating é a classificação geral dos usuários para esse local. É um número inteiro, variando de 1 a 5.
    • text é a avaliação do usuário. Ao avaliar um local com Google Places, as avaliações de texto são consideradas opcionais. Portanto, esse campo pode estar vazio.
  • types: uma matriz de tipos para este local (por exemplo, ["política", "localidade"] ou ["restaurante", "estabelecimento"]).
  • url: URL da página oficial do Google desse local. Essa é a página do estabelecimento no Google+ com as melhores informações disponíveis sobre o local. Os aplicativos devem vincular ou incorporar essa página em todas as telas que mostrem resultados detalhados do local para o usuário.
  • vicinity: um endereço simplificado para o local, incluindo o nome da rua, o número da rua e a localidade, mas não província/estado, código postal ou país. Por exemplo, o escritório da Google em Sidnei, Austrália, tem um valor de vicinity de 5/48 Pirrama Road, Pyrmont. A propriedade vicinity só é retornada para uma Nearby Search.
  • website lista o site oficial para esse local, como a página inicial de um negócio.

Classificações multidimensionais podem não estar disponíveis para todos os locais. Se houver poucas avaliações, a resposta de detalhes incluirá uma avaliação herdada na escala de 0.0 a 5.0 (se disponível) ou nenhuma classificação.

Referência a um local com um ID de local

Os locais em um Google Map podem ser exclusivamente referenciados com o ID de local. IDs de local estão disponíveis para a maioria dos locais, incluindo negócios, pontos turísticos, parques e interseções. Esses IDs são estáveis, ou seja, após identificar o ID do local de uma localização, você poderá reutilizar esse valor na próxima vez que procurar esse local.

Para usar um ID de local no aplicativo, é preciso antes encontrar o ID, que está disponível no PlaceResult retornado por uma solicitação Place Search ou Details. Em seguida, você pode usar o ID de local para pesquisar Place Details ou para ativar Save Attribution em um mapa conectado.

IDs de local estão isentos das restrições de armazenamento em cache definidas na Seção 10.5.d dos Termos de serviço das Google Maps APIs. Portanto, é permitido armazenar valores de ID de local indefinidamente.

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

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

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

Place Photos

O recurso Place Photo permite adicionar conteúdo fotográfico de alta qualidade ao seu site. O serviço Photo permite acessar milhões de fotos armazenadas nos bancos de dados de locais do Places e do Google+. Ao obter informações de local usando uma solicitação de Place Details, são retornadas referências de fotos para o conteúdo fotográfico relevante. As solicitações de Nearby Search e Text Search também retornam uma única referência de foto por local, quando relevante. Usando o serviço Photo, é possível acessar as fotos referenciadas e redimensionar a imagem de acordo com o tamanho ideal para o aplicativo.

Uma matriz de objetos PlacePhoto é retornada como parte do objeto PlaceResult para todas as solicitações getDetails(), textSearch() ou nearbySearch() enviadas ao PlacesService.

Observação: o número de fotos retornadas varia de acordo com a solicitação.

  • Nearby Search e Text Search retornam no máximo um objeto PlacePhoto.
  • Radar Searches não retornam informações de fotos.
  • Uma solicitação Details retorna até dez objetos PlacePhoto.

Você pode solicitar o URL da imagem associada chamando o método PlacePhoto.getUrl() e passando um objeto PhotoOptions válido. O objeto PhotoOptions permite especificar a altura e a largura máximas desejadas para a imagem. Se você especificar um valor para max_height e max_width, o serviço Photo redimensionará a imagem para o menor de dois tamanhos que mantenha a proporção da imagem original.

O fragmento de código a seguir aceita um objeto de local e adiciona um marcador ao mapa, se existir uma foto. A imagem do marcador padrão é substituída por uma pequena versão da foto.

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({'maxWidth': 35, 'maxHeight': 35})
  });
}

Enviar comentários acerca de...

Google Maps Javascript API
Google Maps Javascript API
Precisa de ajuda? Visite a nossa página de apoio técnico.