IDs de local identificam de forma exclusiva um local no banco de dados do Google Places e no Google Maps. Os IDs de lugar são aceitos em solicitações para as seguintes APIs do Maps:
- Recuperar um endereço de um ID de lugar no serviço da Web da API Geocoding e no serviço Geocoding, API Maps JavaScript.
- Especificar waypoints intermediários, de destino e intermediários no serviço da Web da API Directions e na API Directions, API Maps JavaScript.
- Especifique as origens e os destinos no serviço da Web da API Distance Matrix e na API Distance Matrix Service, na API Maps JavaScript.
- Recuperar o Place Details no serviço da Web da API Places, no SDK do Places para Android e no SDK do Places para iOS e na biblioteca do Places, API JavaScript.
- Usar parâmetros de ID de lugar na API Maps Embed.
- Recuperar consultas de pesquisa em URLs do Maps
- Exibir limites de velocidade na API Roads.
- Como encontrar e estilizar polígonos de limite no estilo baseado em dados.
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 lugar abaixo para pesquisar um lugar e receber o ID:
Se preferir, veja o localizador de ID de lugar com o código na documentação da API Maps JavaScript.
Visão geral
Um ID de local é um identificador textual que identifica um local de forma exclusiva. O comprimento do identificador pode variar (não há tamanho máximo para IDs de lugar). Exemplos:
-
ChIJgUbEo8cfqokR5lP9_Wh_DaM -
GhIJQWDl0CIeQUARxks3icF8U8A -
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0EiGhIYChQKEgnRTo6ixx-qiRHo_bbmkCm7ZRAN -
EicxMyBNYXJrZXQgU3QsIFdpbG1pbmd0b24sIE5DIDI4NDAxLCBVU0E -
IhoSGAoUChIJ0U6OoscfqokR6P225pApu2UQDQ
IDs de lugar estão disponíveis para a maioria dos locais, incluindo empresas, pontos turísticos, parques e interseções. É possível que o mesmo local tenha vários IDs de lugar. Os IDs de local podem mudar ao longo do tempo.
Você pode usar o mesmo ID de lugar na API Places e em várias APIs da Plataforma Google Maps. Por exemplo, você pode usar o mesmo ID de lugar para referenciar um lugar na API Places, na API Maps JavaScript, na API Geocoding, na API Maps Embed e na API Roads.
Recuperar detalhes de local usando o ID de local
Os IDs de lugar 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. Depois de identificar o ID de um lugar, você poderá reutilizar esse valor na próxima vez que procurar esse local. Para mais informações, consulte Salvar IDs de lugar para uso posterior abaixo.
Uma maneira comum de usar IDs de lugar é pesquisar um lugar (usando a API Places ou a biblioteca Places na API Maps JavaScript, por exemplo) e, em seguida, usar o ID de lugar retornado para recuperar os detalhes. Você pode armazenar o ID de lugar e usá-lo para recuperar os mesmos detalhes de lugares mais tarde. Leia sobre como salvar IDs de lugar abaixo.
Exemplo de uso da API Places
Com 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' dentro de um raio de 1.500 metros de um ponto em Sydney, Austrália, contendo 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"
}
Para ver uma descrição de todos os campos na resposta, consulte a documentação do Place Search.
Agora você pode enviar uma solicitação do Place Details, inserindo 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 local para uso posterior
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.
Atualizando os IDs de lugares armazenados
Recomendamos atualizar os IDs de lugar se eles tiverem mais de 12 meses. Você pode atualizar os IDs de lugar sem custos financeiros fazendo uma solicitação do Place Details, especificando apenas o campo place_id no parâmetro fields. Isso acionará a SKU Places Details - ID Refresh. No entanto, essa solicitação também pode retornar o código de status NOT_FOUND. Uma estratégia é armazenar a solicitação original que retornou cada ID de lugar. Se um ID de lugar se tornar inválido, será possível emitir novamente essa solicitação para receber novos resultados. Esses resultados podem ou não incluir o lugar original. A solicitação
é cobrada.
Códigos de erro ao usar IDs de lugar
O código de status INVALID_REQUEST indica que o ID do lugar especificado não é válido. INVALID_REQUEST poderá ser retornado quando o ID de lugar tiver sido truncado ou modificado e não estiver mais correto.
O código de status NOT_FOUND indica que o ID de lugar especificado está obsoleto. Um ID de lugar poderá se tornar obsoleto se uma empresa fechar ou mudar de endereço. Os IDs de lugar podem mudar devido a atualizações em grande escala no banco de dados do Google Maps. Nesses casos, um lugar pode receber um novo ID de lugar, e o ID antigo retorna uma resposta NOT_FOUND.
Alguns tipos de IDs de lugar às vezes podem causar uma resposta NOT_FOUND, ou a API pode retornar um ID diferente na resposta. Esses tipos de ID de lugar incluem o seguinte:
- endereços que não existem no Google Maps como endereços precisos, mas que são inferidos com base em vários endereços.
- Trechos de um trajeto longo, em que a solicitação também especifica uma cidade ou localidade.
- Interseções.
- 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 para IDs de lugar). Exemplo:
EpID4LC14LC_4LCo4LCv4LGN4LCo4LCX4LCw4LGNIC0g4LC44LGI4LCm4LGN4LCs4LC-4LCm4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSAmIOCwteCwv-CwqOCwr-CxjSDgsKjgsJfgsLDgsY0g4LCu4LGG4LCv4LC_4LCo4LGNIOCwsOCxi-CwoeCxjeCwoeCxgSwg4LC14LC_4LCo4LCv4LGNIOCwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwsuCwleCxjeCwt-CxjeCwruCwv-CwqOCwl-CwsOCxjSDgsJXgsL7gsLLgsKjgsYAsIOCwuOCwsOCxguCwsOCxjSDgsKjgsJfgsLDgsY0g4LC14LGG4LC44LGN4LCf4LGNLCDgsLjgsK_gsYDgsKbgsL7gsKzgsL7gsKbgsY0sIOCwueCxiOCwpuCwsOCwvuCwrOCwvuCwpuCxjSwg4LCk4LGG4LCy4LCC4LCX4LC-4LCjIDUwMDA1OSwg4LCt4LC-4LCw4LCk4LCm4LGH4LC24LCCImYiZAoUChIJ31l5uGWYyzsR9zY2qk9lDiASFAoSCd9ZebhlmMs7Efc2NqpPZQ4gGhQKEglDz61OZpjLOxHgDJCFY-o1qBoUChIJi37TW2-YyzsRr_uv50r7tdEiCg1MwFcKFS_dyy4