biblioteca Places

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.
Selecione a plataforma: Android iOS JavaScript Serviço da Web

Visão geral

Com as funções na biblioteca Places, na API Maps JavaScript, seu aplicativo pode pesquisar lugares (definidos nessa API como estabelecimentos, localizações geográficas ou pontos de interesse em destaque) contidos em uma área definida, como os limites de um mapa ou os arredores de um ponto fixo.

A API Places oferece um recurso de preenchimento automático que pode ser usado para que seus aplicativos funcionem com o tipo de pesquisa antecipada do campo de pesquisa do Google Maps. Quando um usuário começar a digitar um endereço, o preenchimento automático preencherá o restante. Para mais informações, consulte a documentação de preenchimento automático.

Primeiros passos

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

Ativar APIs

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

Para ver a lista de APIs ativadas:

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

Carregar a biblioteca

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

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

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

Adicionar a API Places à lista de restrições da API da chave de API

A aplicação de restrições de API às chaves limita o uso da chave a uma ou mais APIs ou SDKs. As solicitações para uma API ou um SDK associados à chave de API serão processadas. As solicitações para uma API ou um SDK não associados à chave de API vão falhar. Para restringir uma chave de API para uso com a biblioteca do Places e a API Maps JavaScript, faça o seguinte:
  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.
        Se uma das APIs não estiver na lista, ative-a.
  6. Clique em SALVAR.

Políticas e limites de uso

Cotas

A biblioteca do Places e a API JavaScript compartilham uma cota de uso com a API Places, conforme descrito na documentação de limites de uso da API Places. O limite de taxa de consultas por segundo é aplicado por sessão de usuário, independentemente de quantos usuários compartilham o mesmo projeto.*

Observação: ao carregar a API pela primeira vez, você recebe uma cota inicial de solicitações. Depois de usar essa cota, a API aplica limites de taxa em outras solicitações por segundo. Se muitas solicitações forem feitas em um determinado período, a API retornará um código de resposta OVER_QUERY_LIMIT. O limite de taxa por sessão impede o uso de serviços do lado do cliente nas solicitações em lote. Para solicitações em lote, use nossas APIs de serviços da Web.

Políticas

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

Place Searches

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

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

Solicitações do Find Place

Uma solicitação do Find Place permite pesquisar um lugar por consulta de texto ou número de telefone. Há dois tipos de solicitações do Find Place:

Encontrar um lugar pela consulta

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

  • query (obrigatório) a string de texto para pesquisar, por exemplo, "restaurante" ou "123 Rua Principal" Precisa ser o nome, endereço ou categoria de estabelecimentos. Qualquer outro tipo de entrada pode gerar erros e não tem garantia de retornar resultados válidos. A API Places retornará correspondências candidatos com base nessa string e ordenará os resultados com base na relevância percebida.
  • 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. Pode ser um dos seguintes:

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

O exemplo a seguir mostra uma chamada para findPlaceFromQuery(), pesquisando &&tt;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);
    }
  });
}
Ver exemplo

Encontrar o lugar pelo número de telefone

O recurso "Localizar lugar do número de telefone" leva um número de telefone e retorna um lugar. Para fazer uma solicitação de Find Place from Phone Number, chame o método findPlaceFromPhoneNumber() do PlaceService, que usa 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. Pode ser um dos seguintes valores:

Também é necessário transmitir um método de callback para findPlaceFromPhoneNumber() a fim de 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. Por exemplo, fields: ['formatted_address', 'opening_hours', 'geometry']. Use um ponto ao especificar valores compostos. Por exemplo: opening_hours.weekday_text.

Os campos correspondem aos resultados da Pesquisa de local e são divididos em três categorias de faturamento: "Basic", "Contact" e "Atmosphere". Os campos básicos são faturados na taxa básica e não geram cobranças extras. Os campos "Contact" e "Atmosphere" têm 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 básica 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

Contato

A categoria do contato inclui o campo a seguir: opening_hours
(obsoleto na biblioteca do Places, API Maps JavaScript). Use uma solicitação do Place Details para ver os resultados da opening_hours.

Atmosfera

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

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

Definir o viés de local (métodos Find Place)

Use o parâmetro locationBias para fazer com que o Find Place favoreça os resultados em uma determinada área. Você pode definir locationBias das seguintes maneiras:

Viés 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 Nearby Search

Com a pesquisa por proximidade, você pode procurar lugares dentro de uma área especificada por palavra-chave ou tipo. Uma pesquisa por proximidade precisa sempre incluir um local, que pode ser especificado de duas maneiras:

  • Um 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 por perto é iniciada com uma chamada para o método nearbySearch() do PlacesService, que retornará uma matriz de objetos PlaceResult. Observe que o método nearbySearch() substitui o 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:

  • Escolha uma destas opções:
    • bounds, que precisa ser um objeto google.maps.LatLngBounds definindo a área de pesquisa retangular; ou
    • um location e um radius. O primeiro usa um objeto google.maps.LatLng, e o segundo usa um número inteiro simples, representando o raio do círculo em metros. O raio máximo permitido é de 50 mil metros. Quando rankBy for definido como DISTANCE, você precisará especificar um location, mas não será possível especificar um radius ou bounds.
  • keyword (opcional): um termo que corresponde a todos os campos disponíveis, incluindo, entre outros, nome, tipo e endereço, além de avaliações de clientes e outros conteúdos de terceiros.
  • minPriceLevel e maxPriceLevel (opcional): restringe os resultados apenas aos lugares dentro do intervalo especificado. Os valores válidos variam de 0 (mais acessível) a 4 (mais caro), inclusive.
  • O uso de name foi 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 do Places só retornará os lugares que estiverem abertos para negócios no momento em que a consulta for enviada. Locais que não especificam horário de funcionamento no banco de dados do Google Places não serão retornados se você incluir esse parâmetro 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 deles. A classificação favorecerá os lugares em destaque dentro do raio definido em relação aos lugares por perto correspondentes, mas que têm menos destaque. O destaque pode ser afetado pela classificação do lugar 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 pela distância do location especificado (obrigatório). Não é possível especificar um bounds e/ou radius personalizado se você especificar 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 que correspondem ao tipo especificado. Apenas um tipo pode ser especificado (se mais de um tipo for fornecido, todos os que forem subsequentes à primeira entrada serão ignorados). Veja a lista de tipos compatíveis.

Você também precisa transmitir um método de callback para nearbySearch(), a fim 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]);
    }
  }
}

Ver exemplo

Solicitações Text Search

O serviço Text Search do Google Places é um serviço da Web que retorna informações sobre um conjunto de lugares com base em uma string, por exemplo, "pizza em Nova York" ou "sapatos perto de Ottawa". O serviço responde com uma lista de lugares que correspondem à string de texto e a qualquer viés de local que tenha sido definido. A resposta da pesquisa inclui uma lista de locais. Você pode enviar uma solicitação do 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 a ser pesquisada, 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 tem garantia de retornar resultados válidos. O serviço Places retornará correspondências de candidatos com base nessa string e ordenará os resultados com base na relevância percebida. Esse parâmetro se torna opcional se o parâmetro type também for usado na solicitação de pesquisa.
  • Você também pode fazer o seguinte:
    • openNow: um valor booleano, indicando que o serviço do Places só retornará os lugares que estão abertos para negócios no momento em que a consulta for enviada. Locais que não especificam horário de funcionamento no banco de dados do Google Places não serão retornados se você incluir esse parâmetro na consulta. Definir openNow como false não tem efeito.
    • minPriceLevel e maxPriceLevel: restringe os resultados apenas a lugares dentro do nível de preço especificado. Os valores válidos estão no intervalo de 0 (mais acessível) a 4 (mais caro), incluindo esses dois valores.
    • Escolha uma destas opções:
      • bounds: um objeto google.maps.LatLngBounds que define o retângulo em que a pesquisa será feita.
      • um location e um radius: você pode influenciar os resultados de um círculo especificado transmitindo um parâmetro location e radius. Isso instruirá o serviço do Places a preferir mostrar resultados nesse círculo. Os resultados fora da área definida ainda poderão 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. Somente um tipo pode ser especificado. Se mais de um tipo for fornecido, todos os tipos após a primeira entrada serão ignorados. Consulte a lista de tipos compatíveis.

Você também precisa transmitir um método de callback para textSearch(), a fim de processar 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'), {
      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 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 da falha na 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 da Web ultrapassou a cota de solicitação.
  • REQUEST_DENIED: a página da Web não tem permissão para usar o PlacesService.
  • UNKNOWN_ERROR: não foi possível processar a solicitação do PlacesService devido a um erro no servidor. Se você tentar novamente, a solicitação poderá ser bem-sucedida.
  • 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. Ele pode conter um dos seguintes valores:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Se não houver dados, business_status não será retornado.
  • formatted_address é uma string que contém o endereço legível do lugar. A propriedade formatted_address só é retornada para uma Pesquisa de texto.

    Muitas vezes, esse endereço é 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 "111 8th Avenue, New York, NY" consiste nos seguintes componentes: "111" (o número da rua), "8th Avenue" (o trajeto), "New York" (a cidade) e "NY" (estado dos EUA).

    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: as informações relacionadas à geometria do lugar. Isso inclui:
    • location fornece a latitude e a longitude do lugar.
    • viewport define a janela de visualização preferencial no mapa ao visualizar este lugar.
  • permanently_closed (descontinuado) é uma sinalização booleana indicando se o lugar foi encerrado permanentemente ou temporariamente (valor true). Não use permanently_closed. Em vez disso, use business_status para ver o status operacional de empresas.
  • plus_code (consulte Código de localização aberto e códigos de adição) é uma referência de local codificada, derivada de coordenadas de latitude e longitude, que representa uma área: 1/8000o de um grau por 1/8000o de grau (cerca de 14m x 14m na Linha do Equador) ou menor. Os Plus Codes podem ser usados para substituir endereços em lugares que não existem, ou seja, quando os edifícios não estão numerados ou as ruas não têm nome.

    O Plus Code é formatado como um código global e 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 retornados. No entanto, se o resultado estiver em um local remoto (por exemplo, um oceano ou deserto), apenas o código global poderá ser retornado.
  • html_attributions: uma matriz de atribuições que você precisa exibir ao exibir os resultados da pesquisa. Cada entrada na matriz contém o texto HTML para uma única atribuição. Observação:essa é uma agregação de todas as atribuições de toda a resposta da pesquisa. Portanto, todos os objetos PlaceResult na resposta 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 HEX padrão para a categoria do lugar.
  • name: o nome do lugar.
  • opening_hours pode conter as seguintes informações:
    • open_now é um valor booleano que indica se o lugar está aberto no momento (descontinuado na biblioteca do Places, API Maps JavaScript, use utc_offset_minutes).
  • place_id é um identificador textual que identifica exclusivamente um lugar. Para recuperar informações sobre o lugar, transmita esse identificador na solicitação do Place Details. Saiba mais sobre como fazer referência a um lugar com um ID de lugar.
  • rating contém a classificação do lugar, de 0,0 a 5,0, com base em avaliações agregadas de usuários.
  • types: uma matriz de tipos para este lugar (por exemplo, ["political", "locality"] ou ["restaurant", "lodging"]). Essa matriz pode conter vários valores ou estar vazia. Novos valores podem ser introduzidos sem aviso prévio. Veja a lista de tipos compatíveis.
  • vicinity: um endereço simplificado para o lugar, incluindo o nome e o número da rua e a localidade, mas não a província/estado, o CEP ou o país. Por exemplo, o escritório de Google, Sydney, 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. Outras páginas estão disponíveis pelo objeto PlaceSearchPagination. Para acessar outras páginas, capture 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 quando houver uma página de resultados adicional.
  • nextPage(), uma função que retornará o próximo conjunto de resultados. Depois de executar uma pesquisa, é preciso esperar dois segundos para que a próxima página de resultados esteja disponível.

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

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

TypeScript

// 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;

JavaScript

// 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;
Ver exemplo

Testar amostra

Place Details

Além de fornecer uma lista de locais em uma área, o serviço Places também pode retornar informações detalhadas sobre um lugar específico. Depois que um lugar é retornado em uma resposta de pesquisa de lugar, o ID do lugar pode ser usado para solicitar outros detalhes sobre ele, como endereço completo, número de telefone, avaliações e avaliações dos usuários etc.

Solicitações de Place Details

Os detalhes do lugar 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 recebe uma solicitação com o placeId desejado do lugar e os campos que indicam os tipos de dados de lugar a serem retornados. Saiba mais sobre como fazer referência a um lugar com um código de lugar.

Ele também usa um método de callback, que precisa processar o código de status transmitido na resposta google.maps.places.PlacesServiceStatus, bem como o 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);
  }
}

Ver exemplo

Campos (detalhes do lugar)

O parâmetro fields usa uma matriz de strings (nomes de campo).

Use o parâmetro fields para especificar uma matriz de tipos de dados de lugar a serem retornados. Por exemplo, fields: ['address_component', 'opening_hours', 'geometry']. Use um ponto ao especificar valores compostos. Por 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 básicos são faturados pela taxa básica e não geram cobranças extras. Os campos "Contact" e "Atmosphere" têm 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 ter sido solicitada.

Basic

A categoria básica inclui os seguintes campos:
address_component, 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 (API Placesvicinity, )

Contato

A categoria de contatos inclui os seguintes campos:
formatted_phone_number, international_phone_number, opening_hours e website.

Atmosfera

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

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

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 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 da Web ultrapassou a cota de solicitação.
  • NOT_FOUND O local referenciado não foi encontrado no banco de dados do Places.
  • REQUEST_DENIED: a página da Web não tem permissão para usar o PlacesService.
  • UNKNOWN_ERROR: não foi possível processar a solicitação do PlacesService devido a um erro no servidor. Se você tentar novamente, a solicitação poderá ser bem-sucedida.
  • ZERO_RESULTS: nenhum resultado foi encontrado para esta solicitação.

Resultados de Place Details

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

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

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

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

    Observe os seguintes fatos sobre a matriz address_components[]:

    • A matriz de componentes de endereço pode conter mais componentes do que o formatted_address.
    • A matriz não inclui necessariamente todas as entidades políticas que contêm um endereço, além daquelas incluídas no 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 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 com o tempo para o mesmo endereço. Um componente pode mudar a posição na matriz. O tipo do componente pode mudar. Um componente específico pode estar ausente em uma resposta posterior.
  • business_status indica o status operacional do lugar, se for uma empresa. Ele pode conter um dos seguintes valores:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Se não houver dados, business_status não será retornado.
  • formatted_address: o endereço legível do lugar.

    Muitas vezes, esse endereço é 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 "111 8th Avenue, New York, NY" consiste nos seguintes componentes: "111" (o número da rua), "8th Avenue" (o trajeto), "New York" (a cidade) e "NY" (estado dos EUA).

    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 de números e números.
  • geometry: as informações relacionadas à geometria do lugar. Isso inclui:
    • location fornece a latitude e a longitude do lugar.
    • viewport define a janela de visualização preferencial no mapa ao visualizar este lugar.
  • permanently_closed (descontinuado) é uma sinalização booleana indicando se o lugar foi encerrado permanentemente ou temporariamente (valor true). Não use permanently_closed. Em vez disso, use business_status para ver o status operacional de empresas.
  • plus_code (consulte Código de localização aberto e códigos de adição) é uma referência de local codificada, derivada de coordenadas de latitude e longitude, que representa uma área: 1/8000o de um grau por 1/8000o de grau (cerca de 14m x 14m na Linha do Equador) ou menor. Os Plus Codes podem ser usados para substituir endereços em lugares que não existem, ou seja, quando os edifícios não estão numerados ou as ruas não têm nome.

    O Plus Code é formatado como um código global e 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 retornados. No entanto, se o resultado estiver em um local remoto (por exemplo, um oceano ou deserto), apenas o código global poderá ser retornado.
  • html_attributions: texto de atribuição a ser exibido para esse resultado de lugar.
  • icon: URL para um recurso de imagem que pode ser usado para representar esse tipo de lugar.
  • international_phone_number contém o número de telefone do lugar no formato internacional. O formato internacional inclui o código do país e é prefixado com o sinal de mais (+). Por exemplo, o international_phone_number para o escritório do Google em Sydney, Austrália, é +61 2 9374 4000.
  • name: o nome do lugar.
  • utc_offset Descontinuado na biblioteca do Places, API Maps JavaScript, use utc_offset_minutes.
  • utc_offset_minutes contém o número de minutos em que o fuso horário atual deste lugar está ajustado em relação ao UTC. Por exemplo, para lugares 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 contém as seguintes informações:
    • open_now (descontinuado na biblioteca do Places e na API Maps JavaScript. Use opening_hours.isOpen(). Consulte este vídeo para saber como usar o isOpen com Place Details. é um valor booleano que indica se o lugar está aberto no momento atual.
    • periods[] é uma matriz de períodos de abertura que abrangem sete dias, a partir de domingo, em ordem cronológica. Cada período contém:
      • open contém um par de objetos de dia e hora que descrevem quando o lugar abre:
        • day (um número de 0 a 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 (os valores estão no intervalo de 0000 a 2359). time será informado no fuso horário do lugar.
      • close pode conter um par de objetos de dia e hora que descrevem quando o lugar fecha. Observação: se um lugar estiver sempre aberto, a seção close não aparecerá na resposta. Os aplicativos podem depender de sempre aberto ser representado como um período open contendo day com valor 0 e time com valor 0000, e nenhum close.
    • weekday_text é uma matriz de sete strings que representam os horários de abertura formatados para cada dia da semana. Se um parâmetro language for especificado na solicitação do Place Details, o serviço do Places vai formatar e localizar o horário de funcionamento de acordo com aquele idioma. A ordem dos elementos nessa matriz depende do parâmetro language. Alguns idiomas começam na semana da segunda-feira, enquanto outros começam no domingo.
  • permanently_closed (descontinuado) é uma sinalização booleana indicando se o lugar foi encerrado permanentemente ou temporariamente (valor true). Não use permanently_closed. Em vez disso, use business_status para ver o status operacional de empresas.
  • photos[]: uma matriz de objetos PlacePhoto. Um PlacePhoto pode ser usado para tirar uma foto com o método getUrl(), ou você pode inspecionar o objeto para os seguintes valores:
    • height: a altura máxima da imagem, em pixels.
    • width: a largura máxima da imagem em pixels.
    • html_attributions: o texto de atribuição a ser exibido com esta 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 lugar por meio de uma solicitação do Place Details. Saiba mais sobre como fazer referência a um lugar com um ID de lugar.
  • rating: a classificação do lugar, de 0,0 a 5,0, com base em avaliações agregadas de usuários.
  • reviews: uma matriz de até cinco avaliações. Cada avaliação consiste em vários componentes:
    • aspects[] contém 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 avaliado. Os seguintes tipos são aceitos: appeal, atmosphere, decor, facilities, food, overall, quality e service.
      • 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 avaliação. Comentários anônimos são atribuídos 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.
    • language é um código de idioma IETF que indica o idioma usado na avaliação do usuário. Esse campo contém apenas a tag de idioma principal, não a tag secundária que indica 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 este lugar. Este é um número inteiro, variando de 1 a 5.
    • text a avaliação do usuário. Ao avaliar um local com o Google Places, as avaliações de texto são consideradas opcionais. Portanto, esse campo pode estar vazio.
  • types: uma matriz de tipos para este lugar (por exemplo, ["political", "locality"] ou ["restaurant", "lodging"]). Essa matriz pode conter vários valores ou estar vazia. Novos valores podem ser introduzidos sem aviso prévio. Veja a lista de tipos compatíveis.
  • url: URL da página oficial do Google para este lugar. Essa é a página do Google que contém as melhores informações disponíveis sobre o lugar. Os apps precisam vincular ou incorporar essa página em qualquer tela que mostre resultados detalhados sobre o lugar ao usuário.
  • vicinity: um endereço simplificado para o lugar, incluindo o nome e o número da rua e a localidade, mas não a província/estado, o CEP ou o país. Por exemplo, o escritório de Google, Sydney, Austrália, tem um valor de 5/48 Pirrama Road, Pyrmont de vicinity. A propriedade vicinity só é retornada para uma Pesquisa por proximidade.
  • website lista o site oficial do lugar, como a página inicial de uma empresa.

Observação:as classificações multidimensionais podem não estar disponíveis para todos os locais. Se houver poucas avaliações, a resposta incluirá uma classificação legada em uma escala de 0 a 5,0 (se disponível) ou nenhuma classificação.

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. IDs de lugar estão disponíveis para a maioria dos locais, incluindo empresas, pontos turísticos, parques e interseções.

Para usar um ID de lugar no seu app, primeiro pesquise o ID, que está disponível em PlaceResult de uma solicitação do Place Search ou Details. Você pode usar esse ID de lugar para procurar Detalhes do lugar.

Os IDs de lugar estão isentos das restrições de armazenamento em cache estabelecidas na Seção 3.2.3(a) dos Termos de Serviço da Plataforma Google Maps. Portanto, é possível armazenar valores de ID de lugar para uso posterior. Para ver as práticas recomendadas ao 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);

Fotos do lugar

O recurso Place Photo permite adicionar conteúdo fotográfico de alta qualidade ao seu site. O serviço Fotos oferece acesso a milhões de fotos armazenadas no banco de dados do Places e do Google+ Local. Quando você receber informações do lugar usando uma solicitação do Place Details, as referências a fotos serão retornadas para conteúdo fotográfico relevante. As solicitações do Nearby Search e do Text Search também retornam uma única referência de foto por lugar, quando relevante. Com ele, é possível acessar as fotos referenciadas e redimensionar a imagem para o tamanho ideal para seu aplicativo.

Uma matriz de objetos PlacePhoto será retornada como parte do objeto PlaceResult para qualquer solicitação getDetails(), textSearch() ou nearbySearch() feita em uma PlacesService.

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

  • Uma pesquisa de proximidade ou de texto retornará no máximo um objeto PlacePhoto.
  • Uma solicitação de detalhes retornará até dez objetos PlacePhoto.

É possível solicitar o URL da imagem associada chamando o método PlacePhoto.getUrl() e transmitindo 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 maxHeight e um maxWidth, o serviço de fotos vai redimensionar a imagem para o menor dos dois tamanhos, mantendo a proporção original.

O snippet de código a seguir aceita um objeto de lugar e adiciona um marcador ao mapa se houver 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})
  });
}

As fotos retornadas pelo serviço de fotos são provenientes de vários locais, incluindo proprietários de empresas e fotos de usuários. Na maioria dos casos, essas fotos podem ser usadas sem atribuição ou terão a atribuição necessária incluída como parte da imagem. No entanto, se o elemento photo retornado incluir um valor no campo html_attributions, inclua mais a atribuição no aplicativo sempre que exibir a imagem.