IDs de local

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

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 do SDK do Places para Android

No SDK do Places para Android, é possível recuperar o ID de um lugar chamando Place.getId(). O serviço Place Autocomplete também retorna um ID de lugar para cada lugar que corresponde à consulta de pesquisa e ao filtro fornecidos. Use o ID do lugar para recuperar o objeto Place novamente mais tarde.

Para receber um lugar por ID, chame PlacesClient.fetchPlace(), enviando um FetchPlaceRequest.

A API retorna um FetchPlaceResponse em um Task. O FetchPlaceResponse contém um objeto Place correspondente ao ID de lugar fornecido.

O exemplo de código a seguir mostra a chamada de fetchPlace() para receber detalhes do lugar especificado.

Java


// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

Kotlin


// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

// Specify the fields to return.
val placeFields = listOf(Place.Field.ID, Place.Field.NAME)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

      

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.Field.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