Pronto!

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

Ativar o serviço web da API do Google Places

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

  1. Criar ou selecionar um projeto
  2. Ativar o serviço web da API do Google Places
  3. Criar chaves apropriadas
Continuar

IDs de local

IDs de local identificam de forma exclusiva um local no banco de dados do Google Places e no Google Maps.

  1. Visão geral
  2. Recuperar detalhes de local usando o ID de local
  3. Processar vários IDs de local e escopo de ID de local
  4. Encontrar o ID de um local específico
  5. Salvar IDs de local para uso posterior

Encontrar o ID de um local específico

Está procurando o ID de local de um local específico? Use o localizador de ID de local abaixo para procurar um local e obter o ID:

Uma alternativa é visualizar o localizador de ID de local com seu próprio código na documentação da Google Maps JavaScript API.

Visão geral

Um ID de local é um identificador textual que identifica um local de forma exclusiva. Parece com o exemplo a seguir (o tamanho do identificador pode variar):

ChIJrTLr-GyuEmsRBfy61i59si0

IDs de local estão disponíveis para a maioria dos locais, incluindo empresas, pontos turísticos, parques e interseções. Esses IDs são estáveis, o que significa que, depois de identificar o ID de um local, você poderá reutilizar esse valor na próxima vez em que procurar aquele local.

É possível usar o mesmo ID de local na Google Places API e em diversas Google Maps APIs. Por exemplo, você pode usar o mesmo ID de local para referenciar um local na Places API, na Google Maps JavaScript API, na Google Maps Geocoding API, na Google Maps Embed API e na Google Maps Roads API.

Recuperar detalhes de local usando o ID de local

O ID de local fornece uma forma confiável de referenciar informações de um determinado local. Uma forma comum de usar IDs de local é procurar um local (usando o Google Places API Web Service ou a biblioteca Places na Google Maps JavaScript API, por exemplo) e, em seguida, usar o ID de local retornado para obter os detalhes do local. Você também pode armazenar o ID de local e usá-lo para recuperar os detalhes do mesmo local posteriormente.

Exemplo usando o Places API Web Service

Usando o Google Places API Web Service, você pode encontrar um ID de local por meio de uma solicitação a Place Search.

O exemplo a seguir é uma solicitação de pesquisa por locais de tipo “restaurante” dentro de uma área de 500 m de distância de um ponto em Sydney, Austrália, que contenham a palavra “cruzeiro”:

https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670522,151.1957362&radius=500&type=restaurant&keyword=cruise&key=YOUR_API_KEY

A resposta inclui um ID de local no campo place_id, como é mostrado neste fragmento:

{
  "html_attributions" : [],
  "results" : [
    {
      "geometry" : {
        "location" : {
          "lat" : -33.870775,
          "lng" : 151.199025
        }
      },
      ...
      "place_id" : "ChIJrTLr-GyuEmsRBfy61i59si0",
      ...
    }
  ],
  "status" : "OK"
}

Para ver uma descrição de todos os campos na resposta, consulte a documentação do Place Search.

Agora é possível enviar uma solicitação Place Details com o ID de local no parâmetro placeid:

https://maps.googleapis.com/maps/api/place/details/json?placeid=ChIJrTLr-GyuEmsRBfy61i59si0&key=YOUR_API_KEY

Processar vários IDs de local e escopo de ID de local

Cada ID de local só pode referenciar um local, mas um único local pode ter mais de um ID de local. Os casos mais comuns de gerenciamento de diversos IDs para um mesmo local é quando se adiciona um local inicialmente limitado ao seu aplicativo que depois recebe uma abrangência do nível do Google.

Ao adicionar um local usando o Places API Web Service, recebe-se imediatamente um ID de local para o novo local. O ID do local tem escopo apenas no seu aplicativo. Em seguida, o local entra em uma fila de moderação, aguardando aprovação para adição ao banco de dados do Google Places. Se aprovado, o local receberá um novo ID de local, disponível em todos os aplicativos e no Google Maps. Consulte a documentação sobre como adicionar locais para ver mais detalhes.

Há outras circunstâncias que podem fazer com que um local receba um novo ID de local. Por exemplo, isso pode acontecer se uma empresa se mudar para outra localidade.

O diagrama a seguir mostra um cenário possível em que um local tenha mais de um ID de local:

Recuperar um local com vários IDs

O fato de um local ter diversos IDs não afeta uma eventual solicitação à Places API. No entanto, a resposta é afetada.

Ao solicitar um local especificando um ID de local, você tem a certeza de que sempre receberá o mesmo local na resposta (se o local ainda existir).

Observe, no entanto, que a resposta poderá conter mais de um ID de local para o local solicitado ou um ID de local diferente daquele em sua solicitação.

  • Comportamento no Places API Web Service: Se o local tiver diversos IDs, o Places API Web Service retornará o ID principal do local e uma matriz contendo todos os IDs alternativos. Consulte a documentação sobre detalhes de local e pesquisa de local.
  • Comportamento na Biblioteca JavaScript da Places API e outras APIs: ao solicitar detalhes de local para um ID de local específico, você receberá os detalhes do local solicitado. Observe, no entanto, que o ID de local pode ser diferente se o local recebeu um novo ID após a solicitação anterior. Você pode continuar usando com segurança o ID de local original para acessar o local, mas é recomendável usar o ID de local retornado mais recentemente sempre que possível.

Salvar IDs de local para uso posterior

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

Enviar comentários sobre…

location_on
Google Places API Web Service