Migrar recursos da v3 para o endpoint SearchDestinations

Este produto ou recurso é experimental (pré-GA). Os produtos e recursos pré-GA têm suporte limitado, e é possível que as mudanças neles não sejam compatíveis com versões anteriores. As Soluções pré-GA são cobertas pelos Termos de Serviço da Plataforma Google Maps. Para mais detalhes, consulte as descrições da fase de lançamento.

Desenvolvedores do Espaço Econômico Europeu (EEE)

Se o endereço de faturamento estiver no Espaço Econômico Europeu, a partir de 8 de julho de 2025, os Termos de Serviço da Plataforma Google Maps para o EEE vão se aplicar ao uso dos Serviços. A funcionalidade varia de acordo com a região. Saiba mais.

Os seguintes recursos da API Geocoding v3 estão sendo substituídos pelo endpoint SearchDestinations da API Geocoding v4:

• Entradas
• Pontos de navegação
• Contornos de edifícios
• Acesso geral

Se você estava usando a API Geocoding v3 para os recursos acima, use este documento para ajudar a usar o endpoint SearchDestinations e ter acesso a esses recursos. Este documento explica onde encontrar esses recursos na resposta da API SearchDestinations e as diferenças na forma como eles são representados nas respostas da API entre a API Geocoding v3 e o endpoint SearchDestinations da API Geocoding v4.

Entradas

Para receber as entradas associadas a um destination, use o campo destination.entrances.

O formato de um entrance é um pouco diferente do formato de entrada na API Geocoding v3. Cada entrada em destination.entrances tem os seguintes campos:

• displayName: um novo campo opcional que terá um nome legível para a entrada, por exemplo, "Portão B".
• location: um local do tipo LatLng, que é diferente do formato usado na API Geocoding v3.
• tags: é o mesmo que o campo tags das entradas da API Geocoding v3.
• place: análogo ao campo buildingPlaceId das entradas da API Geocoding v3. No entanto, o ID do lugar neste campo pode ser de um lugar de qualquer tipo, não necessariamente apenas um edifício.

Pontos de navegação

Para receber os pontos de navegação associados a um destination, use o campo destination.navigationPoints.

O formato de um navigationPoint é um pouco diferente do formato de ponto de navegação na API Geocoding v3. Cada ponto de navegação em destination.navigationPoints tem os seguintes campos:

• displayName: um novo campo opcional que terá um nome legível para o ponto de navegação, por exemplo, "5ª Avenida".
• location: um local do tipo LatLng, que é diferente do formato usado na API Geocoding v3.
• travelModes: semelhante ao campo restrictedTravelModes dos pontos de navegação da API Geocoding v3. Os valores de enumeração possíveis são os mesmos. A única diferença é que esse campo agora representa os modos de viagem aceitáveis para o ponto de navegação, em vez dos modos de viagem restritos.
• usage: um novo campo que contém os casos de uso compatíveis com o ponto de navegação. A maioria dos pontos de navegação tem um uso de UNKNOWN, mas isso não significa que o uso do ponto de navegação seja restrito de alguma forma.

Contornos de edifícios

Para receber os contornos de edifícios associados a um destination, use o campo displayPolygon dos objetos placeView no destination que representam edifícios. Para cada placeView, é possível verificar se ele é um edifício com o campo placeView.structureType. Se o tipo de estrutura for BUILDING, você poderá acessar o contorno no campo placeView.displayPolygon. O placeView também terá outros campos para o edifício que não estavam na API Geocoding v3.

Um destination pode ter um objeto placeView que representa um edifício nos seguintes campos:

• destination.primary: é o local principal do destino.
• destination.containingPlaces: é um campo repetido que pode conter lugares maiores que "contêm" o lugar principal. Por exemplo, se o lugar principal for um subpremise, containingPlaces geralmente vai conter o placeView que representa o edifício.
• destination.subDestinations: é um campo repetido que pode conter subdestinos do lugar principal. Por exemplo, unidades individuais de um prédio. Normalmente, esse campo não tem um placeView representando um edifício.

O formato de placeView.displayPolygon corresponde ao formato de contorno do edifício na API Geocoding v3, que é o formato GeoJSON, usando o formato RFC 7946.

Acesso geral

Assim como na criação de contornos, para receber os fundamentos associados a um destination, use o campo displayPolygon dos objetos placeView no destination que representam fundamentos. Para cada placeView, você pode verificar se é um motivo com o campo placeView.structureType. Se o tipo de estrutura for GROUNDS, você poderá extrair o contorno do campo placeView.displayPolygon. O placeView também terá outros campos para os motivos que não estavam na API Geocoding v3.

Um destination pode ter um objeto placeView que representa uma justificativa nos seguintes campos:

• destination.primary
• destination.containingPlaces
• destination.subDestinations

O formato de placeView.displayPolygon corresponde ao formato de contorno de terrenos na API Geocoding v3, que é o formato GeoJSON, usando o formato RFC 7946.

Usar uma máscara de campo para solicitar esses recursos

O endpoint SearchDestinations exige uma máscara de campo, conforme explicado em Escolher campos para retornar. A máscara de campo pode ser definida como * para retornar todos os campos ou como os campos específicos que você quer receber. Por exemplo, a solicitação de API a seguir define a máscara de campo para receber todos os campos necessários para receber as entradas, pontos de navegação, contornos de edifícios e terrenos de um destino:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations