Biblioteca Places

Visão geral

Com as funções na biblioteca Places, a API Maps JavaScript permite que seu aplicativo pesquise lugares (definidos nessa API como estabelecimentos, localizações geográficas ou pontos de interesse importantes) em uma área definida, como limites de um mapa ou ao redor de um ponto fixo.

A API Places disponibiliza um recurso de preenchimento automático para que os aplicativos ofereçam pesquisa durante a digitação no campo de busca do Google Maps. Quando alguém começa a digitar um endereço, o preenchimento automático completa o restante. Para mais informações, consulte a documentação de preenchimento automático.

Começar

Se você não conhece a API Maps JavaScript ou o JavaScript, recomendamos estudar o JavaScript e consultar Ter uma chave de API antes de começar.

Ativar APIs

Antes de usar a biblioteca Places na API Maps JavaScript, verifique se ela está ativada no console do Google Cloud, no mesmo projeto configurado para a API Maps JavaScript.

Para saber quais são as APIs ativadas:

1. Acesse o console do Google Cloud.
2. Clique no botão Selecionar um projeto, escolha o que você configurou para a API Maps JavaScript e selecione Abrir.
3. Na lista de APIs do Painel, procure API Places.
4. A API Places vai aparecer na lista se já estiver ativada. Se não encontrar, faça o seguinte para ativar a API:
   1. Na parte de cima da página, selecione ATIVAR APIs E SERVIÇOS para acessar a guia Biblioteca. Outra opção é selecionar Biblioteca no menu lateral esquerdo.
   2. Pesquise e selecione API Places na lista de resultados.
   3. Clique em ATIVAR. Quando o processo terminar, a API Places vai aparecer na lista de APIs do Painel.

Carregar a biblioteca

O serviço Places é uma biblioteca independente e separada do código principal da API Maps JavaScript. Carregue essa biblioteca usando o parâmetro libraries no URL de inicialização da API Maps para usar as funcionalidades dela:

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

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

Adicionar a API Places à lista de restrições de chaves de API

1. Acesse o console do Google Cloud.
2. Clique na lista suspensa do projeto e selecione o projeto que contém a chave de API que você quer proteger.
3. Clique no botão de menu e escolha Plataforma Google Maps > Credenciais.
4. Na página Credenciais, clique no nome da chave de API que você quer proteger.
5. Na página Restringir e renomear a chave de API, defina as restrições:
   
   • Restrições da API
   • Selecione Restringir chave.
   • Clique em Selecionar APIs e escolha API Maps JavaScript e API Places.
     Vai ser preciso ativar a API que não estiver na lista.
6. Clique em SALVAR.

Políticas e limites de uso

Cotas

A biblioteca Places compartilha uma cota de utilização com a API Places, conforme descrito na documentação sobre limites de uso dessa API.

Políticas

A biblioteca Places e a API Maps JavaScript precisam ser usadas de acordo com as políticas da API Places.

Place Searches

Com o serviço Places, você realiza os seguintes tipos de pesquisa:

• Find Place from Query (Encontrar lugar pela consulta): retorna um lugar com base em uma consulta de texto, por exemplo, o nome ou o endereço de um lugar.
• Find Place from Phone (Encontrar lugar pelo telefone): retorna um lugar com base em um número de telefone.
• Nearby Search (Pesquisa de locais por perto): retorna uma lista de locais por perto com base na localização da pessoa.
• Text Search (Pesquisa por texto): retorna uma lista de locais por perto com base em uma string de pesquisa, por exemplo, "Pizza".
• Place Details requests (Solicitações do Place Details): retornam mais detalhes sobre um lugar, incluindo avaliações dos usuários.

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

Solicitações do Find Place

Com uma solicitação do Find Place, você pesquisa um lugar por consulta de texto ou número de telefone. Há dois tipos de solicitações do Find Place:

• Find Place from Query
• Find Place from Phone Number

Find Place from Query

O recurso Find Place from Query recebe uma entrada de texto e retorna um lugar. A entrada pode ser qualquer tipo de dados de lugar, por exemplo, nome ou endereço da empresa. Para fazer uma solicitação "Find Place from Query", chame o método findPlaceFromQuery() do PlacesService, que aceita os seguintes parâmetros:

• query (obrigatório) A string de texto em que pesquisar, por exemplo, "restaurante" ou "Rua Principal, 123". Precisa ser o nome, endereço ou categoria de estabelecimentos. Qualquer outro tipo de entrada pode gerar erros e não garante o retorno de resultados válidos. A API Places retorna as correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância.
• fields (obrigatório) Um ou mais campos especificando os tipos de dados de lugar a serem retornados.
• locationBias (opcional) Coordenadas que definem a área a ser pesquisada. O tipo pode ser:
  • Um conjunto de coordenadas de latitude/longitude especificadas como LatLngLiteral ou objeto LatLng
  • Limites retangulares (dois pares de latitude/longitude ou um objeto LatLngBounds)
  • Raio (em metros) centralizado em uma latitude/longitude

Também é necessário transmitir um método de callback para findPlaceFromQuery(), o que permite processar o objeto de resultados e a resposta google.maps.places.PlacesServiceStatus.

O exemplo a seguir mostra uma chamada para findPlaceFromQuery(), pesquisando "Museu de Arte Contemporânea da Austrália" e incluindo os campos name e geometry.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

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

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

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

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}

Find Place from Phone Number

O serviço "Find Place from Phone Number" recebe um número de telefone e retorna um lugar. Para fazer uma solicitação "Find Place from Phone Number", chame o método findPlaceFromPhoneNumber() do PlacesService, que aceita os seguintes parâmetros:

• phoneNumber (obrigatório) Um número de telefone no formato E.164.
• fields (obrigatório) Um ou mais campos especificando os tipos de dados de lugar a serem retornados.
• locationBias (opcional) Coordenadas que definem a área a ser pesquisada. O tipo pode ser:
  • Um conjunto de coordenadas de latitude/longitude especificadas como LatLngLiteral ou objeto LatLng
  • Limites retangulares (quatro pontos de latitude/longitude ou um objeto LatLngBounds)
  • Raio (em metros) centralizado em uma latitude/longitude

Também é necessário transmitir um método de callback para findPlaceFromPhoneNumber(), o que permite processar o objeto de resultados e a resposta google.maps.places.PlacesServiceStatus.

Campos (métodos Find Place)

Use o parâmetro fields para especificar uma matriz de tipos de dados de lugar a serem retornados. Exemplo: fields: ['formatted_address', 'opening_hours', 'geometry']. Use um ponto quando especificar valores compostos. Exemplo: opening_hours.weekday_text.

Os campos correspondem aos resultados do Place Search e são divididos em três categorias de faturamento: "Basic", "Contact" e "Atmosphere". Os campos "Basic" são faturados na taxa básica e não geram cobranças extras. Os campos "Contact" e "Atmosphere" são faturados em uma taxa maior. Consulte a tabela de preços para mais informações. As atribuições (html_attributions) são sempre retornadas a cada chamada, independentemente de o campo ter sido solicitado.

Basic

A categoria "Basic" inclui os seguintes campos:
business_status, formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color, name, permanently_closed (descontinuado), photos, place_id, plus_code, types

Contact

Atmosphere

Os métodos findPlaceFromQuery() e findPlaceFromPhoneNumber() usam os e podem retornar os mesmos campos nas respectivas respostas.

Definir direcionamento de local (métodos Find Place)

Use o parâmetro locationBias para fazer com que o Find Place favoreça os resultados de uma determinada área. É possível definir locationBias assim:

Direcionamento dos resultados para uma área específica:

locationBias: {lat: 37.402105, lng: -122.081974}

Defina uma área retangular para pesquisar:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

Você também pode usar um LatLngBounds.

Defina um raio para pesquisar (em metros) centralizado em uma área específica:

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

Solicitações do Nearby Search

Uma Nearby Search permite pesquisar locais em uma área especificada por palavra-chave ou tipo. Ela precisa sempre incluir um local, que pode ser especificado de duas formas:

• LatLngBounds.
• uma área circular definida como a combinação da propriedade location, especificando o centro do círculo como um objeto LatLng, e um raio, medido em metros.

Uma pesquisa do Places Nearby é iniciada com uma chamada para o método nearbySearch() do PlacesService, que retorna uma matriz de objetos PlaceResult. 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 precisa ser um Objeto google.maps.LatLngBounds que define o retângulo área de pesquisa. A distância diagonal máxima para os limites área é de aproximadamente 100.000 metros.
  • um location e um radius. O primeiro usa um objeto google.maps.LatLng e o último usa um número inteiro simples, representando o raio do círculo em metros. O máximo raio permitido é de 50.000 metros. Quando rankBy for definido como DISTÂNCIA, você vai ter que especificar um location, mas não vai ser possível especificar um radius ou bounds.
• keyword (opcional): um termo que deve ser comparado com todos os campos disponíveis, inclusive, entre outros, nome, tipo e endereço, avaliações de clientes e outros materiais de terceiros.
• minPriceLevel e maxPriceLevel (opcional): restringe os resultados apenas aos lugares no intervalo especificado. Valores válidos estão no intervalo de 0 (mais barato) a 4 (mais caro).
• name descontinuado. Equivalente a keyword. Os valores nesse campo são combinados com os valores no campo keyword e transmitidos como parte da mesma string de pesquisa.
• openNow (opcional): um valor booleano indicando que o serviço Places precisa 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 vão ser retornados se esse parâmetro for incluído na consulta. Definir openNow como false não tem efeito.
• rankBy (opcional): especifica a ordem em que os resultados são listados. Valores possíveis:
  • 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 vai priorizar os locais com mais destaque. O destaque pode ser afetado pela classificação de um local no índice do Google, pela popularidade global e 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 do location especificado (obrigatório). Não é possível especificar um bounds e/ou radius personalizado se você definir RankBy.DISTANCE. Quando você especifica RankBy.DISTANCE, é necessário informar um ou mais parâmetros keyword, name ou type.
• type: restringe os resultados aos lugares correspondentes ao tipo especificado. Só um tipo pode ser especificado (se mais de um tipo for fornecido, todos os outros após a primeira entrada vão ser ignorados). Consulte a lista de tipos compatíveis.

Também é necessário transmitir um método de callback para nearbySearch() com o objetivo de processar o objeto de resultados e a 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'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    type: ['restaurant']
  };

  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++) {
      createMarker(results[i]);
    }
  }
}

Exemplo

Solicitações Text Search

A 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 São Paulo", "loja de sapatos perto do Rio de Janeiro". 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 mais informações sobre qualquer um dos locais na resposta.

As pesquisas de texto são iniciadas com uma chamada para o método textSearch() do 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 em que pesquisar, por exemplo, "restaurante" ou "Rua Principal, 123". Precisa ser o nome, endereço ou categoria de estabelecimentos. Qualquer outro tipo de entrada pode gerar erros e não garante o retorno de resultados válidos. O serviço Places retorna as correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância. Esse parâmetro se torna opcional se o parâmetro type também é usado na solicitação de pesquisa.
• Opcionalmente:
  • openNow: um valor booleano indicando que o serviço Places precisa 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 vão ser retornados se esse parâmetro for incluído na consulta. Definir openNow como false não tem efeito.
  • minPriceLevel e maxPriceLevel: restringe os resultados apenas a lugares no nível de preço especificado. Valores válidos estão no intervalo de 0 (mais barato) a 4 (mais caro).
  • Uma das seguintes opções:
    • bounds, que precisa ser um Objeto google.maps.LatLngBounds que define o retângulo área de pesquisa. A distância diagonal máxima para os limites área é de aproximadamente 100.000 metros.
    • Um location e um radius: você pode influenciar os resultados de um círculo especificado ao transmitir um parâmetro location e radius. Isso vai instruir o serviço Places para mostrar preferencialmente os resultados dentro desse círculo. Os resultados fora da área definida ainda podem ser exibidos. O local usa um objeto google.maps.LatLng, e o raio recebe um número inteiro simples, representando o raio do círculo em metros. O raio máximo permitido é de 50.000 metros.
  • type: restringe os resultados aos lugares correspondentes ao tipo especificado. Só um tipo pode ser especificado (se mais de um tipo for fornecido, todos os outros após a primeira entrada vão ser ignorados). Veja a lista de tipos compatíveis.

Também é necessário transmitir um método de callback para textSearch() com o objetivo de processar o objeto de resultados e a 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'), {
      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 a rastrear o motivo da falha da solicitação de lugar. Os valores de status possíveis são:

• INVALID_REQUEST: esta solicitação era 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. Se você tentar novamente, a solicitação poderá dar certo.
• ZERO_RESULTS: nenhum resultado foi encontrado para esta solicitação.

Resultados de Place Search

As funções findPlace(), nearbySearch() e textSearch() retornam uma matriz de objetos PlaceResult.

Cada objeto PlaceResult pode incluir as seguintes propriedades:

• business_status indica o status operacional do lugar, se for uma empresa, e pode conter um dos seguintes valores:
  • OPERATIONAL
  • CLOSED_TEMPORARILY
  • CLOSED_PERMANENTLY
  Se não houver dados, business_status não vai ser retornado.
• formatted_address é uma string que contém o endereço legível do local. A propriedade formatted_address só é retornada para uma Pesquisa de texto.

  Esse endereço costuma ser equivalente ao endereço postal. Alguns países, como o Reino Unido, não permitem a distribuição de endereços postais verdadeiros devido a restrições de licenciamento.

  O endereço formatado é composto de maneira lógica por um ou mais componentes de endereço. Por exemplo, o endereço "Avenida Paulista, 111, São Paulo, SP" consiste nos seguintes componentes: "Avenida Paulista" (o trajeto), "111" (o número), "São Paulo" (a cidade) e "SP" (o estado brasileiro).

  Não analise o endereço formatado de maneira programática. Em vez disso, use os componentes de endereço individuais, que a resposta da API inclui, além do campo de endereço formatado.

• geometry: informações relacionadas à geometria do local. Isso inclui o seguinte:
  • location informa a latitude e a longitude do local.
  • viewport define a janela de visualização preferida no mapa ao visualizar este local.
• permanently_closed (descontinuado) é uma sinalização booleana que indica se o lugar foi encerrado de forma permanente ou temporária (valor true). Não use permanently_closed. Em vez disso, use business_status para ver o status de funcionamento das empresas.
• plus_code (consulte Open Location Code e Plus Codes; links em inglês) é uma referência de local codificada, derivada de coordenadas de latitude e longitude, que representa uma área: 1/8000 de um grau por 1/8000 de um grau (aproximadamente 14m x 14m na Linha do Equador) ou menor. Os Plus Codes podem ser usados em vez de endereços nos lugares em que não existem, ou seja, quando os imóveis não estão numerados ou as ruas não têm nome.

  O Plus Code é formatado como um código global e um composto:

  • global_code é um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres (849VCWC8+R9).
  • compound_code é um código local com, pelo menos, seis caracteres e um local explícito (CWC8+R9, Mountain View, CA, EUA). Não analise esse conteúdo de forma programática.
  Normalmente, tanto o código global quanto o composto são trazidos. No entanto, se o resultado estiver em um local remoto (por exemplo, um oceano ou deserto), apenas o código global vai ser retornado.
• html_attributions: uma matriz de atribuições que precisam aparecer com os resultados da pesquisa. Cada entrada na 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. Todos os objetos PlaceResult na resposta, portanto, contêm listas de atribuição idênticas.
• icon retorna o URL de um ícone PNG colorido de 71 x 71 pixels.
• icon_mask_base_uri retorna o URL base de um ícone não colorido, menos a extensão .svg ou .png.
• icon_background_color retorna o código de cor hexadecimal padrão para a categoria do local.
• name: o nome do local.
• opening_hours pode conter as seguintes informações:
  • open_now é um valor booleano que indica se o local está aberto no momento (descontinuado na biblioteca Places, na API Maps JavaScript, use utc_offset_minutes).
• place_id é um identificador textual que determina um local de forma exclusiva. Para recuperar informações sobre o local, transmita esse identificador na solicitação do Place Details. Saiba mais sobre como fazer referência a um local com o respectivo ID.
• rating contém a nota do lugar (0,0 a 5,0), com base nas avaliações de usuários agregadas.
• types: uma matriz de tipos para esse lugar (por exemplo, ["political", "locality"] ou ["restaurant", "lodging"]). Essa matriz pode conter diversos valores ou estar vazia. Novos valores podem ser adicionados sem aviso prévio. Consulte a lista de tipos compatíveis.
• 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 do Google em Sydney, na Austrália, tem um valor de 5/48 Pirrama Road, Pyrmont de vicinity.

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 estão disponíveis no objeto PlaceSearchPagination. Para acessar outras páginas, é necessário capturar o objeto PlaceSearchPagination usando uma função de callback. O objeto PlaceSearchPagination é definido como:

• hasNextPage é uma propriedade booleana que indica se outros resultados estão disponíveis. true é usado quando há 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 precisa ser mostrada antes da próxima. Cada pesquisa conta como uma única solicitação em relação aos limites de uso.

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

// 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 initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const 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),
      };

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

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

// 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 initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    },
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const 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),
      };

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

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
index.js

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 lugar pode ser usado para pedir mais detalhes, como endereço completo, telefone, classificações e avaliações de usuários.

Solicitações do 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 do lugar e campos que indicam quais tipos de dados do Places retornar. Saiba mais sobre como fazer referência a um local com o respectivo ID.

Ele também recebe um método de callback, que precisa lidar com o código de status transmitido na resposta google.maps.places.PlacesServiceStatus, além do objeto google.maps.places.PlaceResult.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

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

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

Exemplo

Fields (detalhes do lugar)

Use o parâmetro fields para especificar uma matriz de tipos de dados de lugar a serem retornados. Exemplo: fields: ['address_components', 'opening_hours', 'geometry']. Use um ponto quando especificar valores compostos. Exemplo: opening_hours.weekday_text.

Os campos correspondem aos resultados do Place Details e são divididos em três categorias de faturamento: "Basic", "Contact" e "Atmosphere". Os campos "Basic" são faturados na taxa básica e não geram cobranças extras. Os campos "Contact" e "Atmosphere" são faturados em uma taxa maior. Consulte a tabela de preços para mais informações. As atribuições (html_attributions) são sempre retornadas a cada chamada, independente de terem sido solicitadas.

Basic

A categoria "Basic" inclui os seguintes campos:
address_components ,adr_address ,business_status , formatted_address ,geometry ,icon , icon_mask_base_uri ,icon_background_color ,name , permanently_closed (descontinuado)photo ,place_id ,plus_code ,type , url ,utc_offset (descontinuado na biblioteca Places, na API Maps JavaScript),utc_offset_minutes, vicinity

Contact

A categoria "Contact" inclui os seguintes campos:
formatted_phone_number, international_phone_number,opening_hours e website.

Atmosphere

A categoria "Atmosphere" inclui os seguintes campos: price_level, rating, reviews, user_ratings_total

Saiba mais sobre os campos de local. Para mais informações sobre como as solicitações de dados de lugar são faturadas, consulte Uso e faturamento.

Respostas do 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 que ajudam a rastrear o motivo da falha na solicitação do Place Details. Os valores de status possíveis são:

• INVALID_REQUEST: esta solicitação era 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 indicado 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. Se você tentar novamente, a solicitação poderá dar certo.
• ZERO_RESULTS: nenhum resultado foi encontrado para esta solicitação.

Resultados do Place Details

Uma chamada getDetails() que funciona retorna um objeto PlaceResult com as seguintes propriedades:

• address_components: uma matriz contendo os componentes separados aplicáveis a esse endereço.

  Normalmente, cada componente de endereço contém os seguintes campos:

  • types[] é uma matriz que indica o tipo do componente de endereço. Consulte a lista de tipos compatíveis.
  • long_name é a descrição completa em texto ou o nome do componente do endereço retornado pelo geocodificador.
  • short_name é um nome abreviado, no formato de texto, para o componente de endereço, se estiver disponível. Por exemplo, um componente de endereço para o estado do Alasca pode ter um long_name de "Alaska" e um short_name de "AK", usando a abreviação postal de 2 letras.

  Observe os seguintes fatos sobre a matriz address_components[]:

  • A matriz de componentes de endereço pode conter mais componentes do que formatted_address.
  • A matriz não inclui necessariamente todas as entidades políticas que contêm um endereço, além daquelas incluídas em formatted_address. Para recuperar todas as entidades políticas que contêm um endereço específico, use a geocodificação inversa, transmitindo a latitude/longitude do endereço como um parâmetro para a solicitação.
  • Não há garantia de que o formato da resposta vai permanecer o mesmo entre as solicitações. Especificamente, o número de address_components varia de acordo com o endereço solicitado e pode mudar para o mesmo endereço. Um componente pode mudar a posição na matriz. O tipo do componente pode mudar. Pode faltar um componente específico em uma resposta posterior.
• business_status indica o status operacional do lugar, se for uma empresa, e pode conter um dos seguintes valores:
  • OPERATIONAL
  • CLOSED_TEMPORARILY
  • CLOSED_PERMANENTLY
  Se não houver dados, business_status não vai ser retornado.
• formatted_address: o endereço legível do lugar.

  Esse endereço costuma ser equivalente ao endereço postal. Alguns países, como o Reino Unido, não permitem a distribuição de endereços postais verdadeiros devido a restrições de licenciamento.

  O endereço formatado é composto de maneira lógica por um ou mais componentes de endereço. Por exemplo, o endereço "Avenida Paulista, 111, São Paulo, SP" consiste nos seguintes componentes: "Avenida Paulista" (o trajeto), "111" (o número), "São Paulo" (a cidade) e "SP" (o estado brasileiro).

  Não analise o endereço formatado de maneira programática. Em vez disso, use os componentes de endereço individuais, que a resposta da API inclui, além do campo de endereço formatado.

• formatted_phone_number: o número de telefone do lugar, formatado de acordo com a convenção regional do número.
• geometry: informações relacionadas à geometria do local. Isso inclui o seguinte:
  • location informa a latitude e a longitude do local.
  • viewport define a janela de visualização preferida no mapa ao visualizar este local.
• permanently_closed (descontinuado) é uma sinalização booleana que indica se o lugar foi encerrado de forma permanente ou temporária (valor true). Não use permanently_closed. Em vez disso, use business_status para ver o status de funcionamento das empresas.
• plus_code (consulte Open Location Code e Plus Codes; links em inglês) é uma referência de local codificada, derivada de coordenadas de latitude e longitude, que representa uma área: 1/8000 de um grau por 1/8000 de um grau (aproximadamente 14m x 14m na Linha do Equador) ou menor. Os Plus Codes podem ser usados em vez de endereços nos lugares em que não existem, ou seja, quando os imóveis não estão numerados ou as ruas não têm nome.

  O Plus Code é formatado como um código global e um composto:

  • global_code é um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres (849VCWC8+R9).
  • compound_code é um código local com, pelo menos, seis caracteres e um local explícito (CWC8+R9, Mountain View, CA, EUA). Não analise esse conteúdo de forma programática.
  Normalmente, tanto o código global quanto o composto são trazidos. No entanto, se o resultado estiver em um local remoto (por exemplo, um oceano ou deserto), apenas o código global vai ser retornado.
• 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.
• international_phone_number: contém o número de telefone do local no formato internacional. O formato internacional inclui o código do país e é prefixado pelo 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 Descontinuado na biblioteca Places, na API Maps JavaScript, use utc_offset_minutes.
• utc_offset_minutes: contém a diferença em minutos entre o fuso horário do lugar em questão e o UTC. Por exemplo, para locais em Sydney, na Austrália, durante o horário de verão, o valor seria 660 (11 horas à frente do UTC) e, para lugares na Califórnia, fora do horário de verão, seria -480 (8 horas atrás do UTC).
• opening_hours contém as seguintes informações:
  • open_now (descontinuado na biblioteca Places, na API Maps JavaScript; use opening_hours.isOpen(). Assista a este vídeo para saber como usar isOpen com o Place Details.) é um valor booleano, que indica se o lugar está aberto no horário atual.
  • periods[]: é uma matriz de períodos de funcionamento cobrindo sete dias, começando no 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-6, correspondente aos dias da semana, começando no 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). O time vai ser relatado no fuso horário do lugar.
    • close pode conter um par de objetos de dia e hora que descrevem o horário de fechamento do local. Observação: se um lugar estiver sempre aberto, a seção close não vai aparecer na resposta. Os aplicativos têm o status de "sempre aberto" representado como um período open período contendo day com valor 0 e time com valor 0000, sem close.
  • weekday_text é uma matriz de sete strings que representam os horários de funcionamento formatados para cada dia da semana. Se um parâmetro language for especificado na solicitação do Place Details, o serviço Places vai direcionar os resultados para avaliações escritas naquele idioma. A ordem dos elementos nessa matriz depende do parâmetro language. Alguns idiomas iniciam a semana na segunda-feira e outros no domingo.
• permanently_closed (descontinuado) é uma sinalização booleana que indica se o lugar foi encerrado de forma permanente ou temporária (valor true). Não use permanently_closed. Em vez disso, use business_status para ver o status de funcionamento das empresas.
• 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 que vai ser mostrado 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 ele com uma solicitação do Place Details. Saiba mais sobre como fazer referência a um local com o respectivo ID.
• rating: a nota do lugar (0,0 a 5,0), com base nas avaliações de usuários agregadas.
• reviews: uma matriz de até cinco avaliações. Cada uma delas consiste em vários componentes:
  • aspects[]: contém uma matriz de objetos PlaceAspectRating, cada uma fornecendo uma classificação de um único atributo do estabelecimento. O primeiro objeto na matriz é considerado o aspecto principal. Cada PlaceAspectRating é definido como:
    • type é o nome do aspecto que está sendo avaliado. Os seguintes tipos são aceitos: appeal, atmosphere, decor, facilities, food, overall, quality e service.
    • rating: avaliação do usuário para este aspecto em particular, entre 0 a 3.
  • author_name: o nome do usuário que enviou a avaliação. Comentários anônimos são atribuídos a "Alguém que usa o Google". Se o parâmetro de idioma foi definido, a frase "Alguém que usa o Google" vai retornar uma string localizada.
  • author_url: o URL para o perfil do Google+ das pessoas, 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: classificação geral do usuário para este lugar. É um número inteiro, de 1 a 5.
  • text: avaliação do usuário. Ao avaliar um local com o Google Places, as avaliações de texto são opcionais. Portanto, esse campo pode ficar vazio.
• types: uma matriz de tipos para esse lugar (por exemplo, ["political", "locality"] ou ["restaurant", "lodging"]). Essa matriz pode conter diversos valores ou estar vazia. Novos valores podem ser adicionados sem aviso prévio. Consulte a lista de tipos compatíveis.
• 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 precisam vincular ou incorporar essa página em todas as telas que mostrem resultados detalhados do local para as pessoas.
• 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 do Google em Sydney, na Austrália, tem um valor de 5/48 Pirrama Road, Pyrmont de vicinity. A propriedade vicinity só é retornada para uma Pesquisa nas proximidades.
• website: lista o site oficial do lugar, como a página inicial da empresa na Web.

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

Usar o componente Place Overview

Observação: este exemplo usa uma biblioteca de código aberto. Confira o README para receber suporte e feedback relacionados à biblioteca.

Teste componentes da Web. Use o Componente da Web "Visão geral do lugar" para ver detalhes do lugar com uma representação visual.

Fazer referência a um local com um ID de local

Um ID de lugar é uma referência exclusiva a um local em um mapa do Google. Esses IDs estão disponíveis para a maioria dos lugares, incluindo empresas, pontos turísticos, parques e cruzamentos.

Para usar um ID de lugar no app, encontre antes o ID, que está disponível no PlaceResult retornado por uma solicitação do Place Search ou Details. Você pode usar esse ID de lugar para procurar no Place Details.

Os IDs de lugares estão isentos das restrições de armazenamento em cache definidas na Seção 3.2.3(b) dos Termos de Serviço da Plataforma Google Maps. Portanto, você pode armazenar os valores desses IDs para usar depois. Para ver as práticas recomendadas na hora de armazenar IDs de lugar, consulte a visão geral de IDs de lugar.

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 Photo (Foto do lugar)

Com o recurso Place Photo, você adiciona fotos 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+. Quando você consegue informações de local usando uma solicitação do 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 vai ser retornada como parte do objeto PlaceResult para qualquer solicitação getDetails(), textSearch() ou nearbySearch() feita para um PlacesService.

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

• Uma solicitação de Nearby Search ou Text Search retorna, no máximo, um objeto PlacePhoto.
• Uma solicitação de Details retorna até dez objetos PlacePhoto.

Para solicitar o URL da imagem associada, chame o método PlacePhoto.getUrl() e transmita um objeto PhotoOptions válido. O objeto PhotoOptions permite especificar a altura e a largura máximas da imagem. Se você especificar um valor para maxHeight e maxWidth, o serviço de fotos vai 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})
  });
}

Fotos retornadas pelo serviço Photo têm origem em vários locais, inclusive de proprietários de empresas e imagens enviadas pelos usuários. Na maioria dos casos, essas fotos podem ser usadas sem atribuição ou a atribuição necessária vai ser incluída na imagem. No entanto, se o elemento photo retornado incluir um valor no campo html_attributions, vai ser necessário incluir a atribuição adicional no aplicativo sempre que você mostrar a imagem.