IDs de lugares

Selecione a plataforma: Android iOS JavaScript Web Service
Desenvolvedores do Espaço Econômico Europeu (EEE)

Introdução

IDs de lugares identificam um local de modo exclusivo no banco de dados do Google Places e no Google Maps. Os IDs de lugares são aceitos nas seguintes solicitações às APIs Maps:

  • Recuperar o endereço de um ID de lugar na API Geocoding e no serviço Geocoding da API Maps JavaScript.
  • Especificar waypoints de origem, destino e intermediários na API Routes e na API Directions (legado) e no serviço Directions da API Maps JavaScript (legado).
  • Especificar as origens e os destinos na API Routes, na API Distance Matrix (legada) e no serviço Distance Matrix da API Maps JavaScript (legado).
  • Recuperar Place Details na API Places (nova), no SDK do Places para Android (novo), no SDK do Places para iOS (novo) e na biblioteca Places.
  • Usar parâmetros de ID do lugar na API Maps Embed.
  • Recuperar consultas de pesquisa em URLs do Maps
  • Mostrar limites de velocidade na API Roads.
  • Encontrar e estilizar polígonos de limites com base em dados.

Encontrar o ID de um lugar específico

Está procurando o ID de um lugar específico? Use o localizador abaixo para pesquisar um lugar e conseguir o ID dele:

Também é possível usar o localizador de IDs de lugares com o respectivo código na documentação da API Maps JavaScript.

Encontrar IDs de lugar usando código ou um agente de IA

O localizador de IDs de lugar procura um lugar por vez em um navegador. Para pesquisar IDs de lugar em um app, script ou agente de IA, chame uma API:

Visão geral

O ID de lugar é um indicador textual que identifica um local de forma exclusiva. O tamanho do ID pode variar (não há limite máximo). Exemplos:

  • ChIJgUbEo8cfqokR5lP9_Wh_DaM
  • GhIJQWDl0CIeQUARxks3icF8U8A
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN
  • EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E
  • IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ

Os IDs de lugares estão disponíveis para a maioria dos locais, incluindo empresas, pontos turísticos, parques e cruzamentos. Cada local pode ter vários IDs, que estão sujeitos a mudança com o passar do tempo.

Você pode usar o mesmo ID de lugar na API Places e em várias APIs da Plataforma Google Maps. Por exemplo, use o mesmo ID para identificar um lugar nas APIs Places, Maps JavaScript, Geocoding, Maps Embed e Roads.

Recuperar detalhes usando o ID de lugar

Uma maneira comum de usar IDs de lugar é pesquisar um local usando a API Places ou a biblioteca Places na API Maps JavaScript. Em seguida, use o ID de lugar retornado para recuperar os detalhes do lugar. Armazene o ID de lugar e use posteriormente para recuperar os detalhes do mesmo local. Leia sobre como salvar IDs de lugar mais adiante neste documento.

Os exemplos a seguir mostram como solicitar um URL de ícone para a API Places (nova) e a API Places (legada).

API Places (nova)

Com a API Places, você pode encontrar um ID de lugar fazendo uma solicitação de Text Search (novo).

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

A resposta inclui um ID de lugar no campo id, conforme mostrado abaixo:

{
  "places": [
    {
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
  ...
}

Agora você pode fazer uma solicitação do Place Details (novo) incluindo o ID de lugar no URL da solicitação:

https://places.googleapis.com/v1/places/ChIJs5ydyTiuEmsR0fRSlU0C7k0?fields=id,displayName&key=API_KEY

API Places (legada)

Usando a API Places, você pode encontrar um ID de lugar fazendo uma solicitação do Place Search.

O exemplo a seguir é uma solicitação de pesquisa de lugares do tipo "restaurante" em um raio de 1.500 m de um ponto em Sydney, Austrália, que contém a palavra "cruzeiro":

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

A resposta inclui um ID de lugar no campo place_id, como mostrado neste snippet:

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

Agora você pode enviar uma solicitação do Place Details (legado), colocando o ID de lugar no parâmetro place_id:

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

Salvar IDs de lugares para uso posterior

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.

Atualizar IDs de lugares armazenados

Como os IDs de lugar podem mudar devido a atualizações no banco de dados do Google Maps, o Google recomenda atualizar os IDs de lugar com mais de 12 meses. Atualize os IDs de lugar sem custos financeiros fazendo uma solicitação do Place Details e especificando apenas o campo de ID de lugar no parâmetro fields.

API Places (nova)

Por exemplo, usando Place Details (novo):

https://places.googleapis.com/v1/places/ChIJ05IRjKHxEQ0RJLV_5NLdK2w?fields=id&key=API_KEY

API Places (legada)

Por exemplo, usando a API Places (legada):

https://maps.googleapis.com/maps/api/place/details/json?place_id=ChIJ05IRjKHxEQ0RJLV_5NLdK2w&fields=place_id&key=API_KEY

Essa chamada aciona a SKU Place Detail New Essentials IDs Only ou Places Details - ID Refresh.

Códigos de erro ao usar IDs de lugares

INVALID_REQUEST

O código de status INVALID_REQUEST indica que o ID de lugar especificado não é válido. É possível que INVALID_REQUEST seja retornado quando o ID for truncado ou modificado e não estiver mais correto.

NOT_FOUND

O código de status NOT_FOUND indica que o ID de lugar especificado está obsoleto. Um ID se torna obsoleto quando uma empresa fecha ou muda para outro local. Os IDs de lugar também podem mudar devido a atualizações no banco de dados do Google Maps. Nesses casos, um lugar recebe um novo ID, e o ID antigo retorna uma resposta NOT_FOUND.

Para atualizar os resultados no caso de um ID de lugar obsoleto, armazene a solicitação original que retornou cada ID de lugar e repita a solicitação conforme necessário. A solicitação reemitida é faturada na SKU apropriada.

Alguns tipos de IDs de lugar podem gerar uma resposta NOT_FOUND, ou a API pode retornar um ID diferente. Esses tipos de ID de lugar incluem:

  • Endereços que não são exatos no Google Maps, mas são inferidos de um intervalo de endereços.
  • Trechos de um trajeto longo, em que a solicitação também especifica uma cidade ou região administrativa.
  • Cruzamentos.
  • Lugares com um componente de endereço do tipo subpremise.

Esses IDs geralmente assumem a forma de uma string longa (não há tamanho máximo). Por exemplo:

EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4