Migrar da API Geocoding v3 para a v4

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

A API Geocoding v4 apresenta vários novos endpoints que substituem a funcionalidade na v3 da API. Este guia mostra como migrar seu app para usar os novos endpoints da v4.

Você pode usar as chaves de API atuais com os novos endpoints da v4. No entanto, se você solicitou um aumento de cota na v3 da API, peça um aumento nas novas APIs v4.

Migrar da geocodificação direta v3

Se você usa a geocodificação para geocodificar endereços, migre para o endpoint v4 Geocodificar um endereço, que aceita uma solicitação GET.

A API v4 muda nomes, estrutura e suporte para vários parâmetros. Recomendamos usar uma máscara de campo para especificar os campos que você quer retornar na resposta.

Mudanças nos parâmetros de solicitação

Parâmetro v3 Parâmetro v4 Observações
address, components address O endereço não estruturado (v3 address) agora é transmitido no caminho do URL. Os filtros de componentes (v3 components) agora são transmitidos como parâmetros de consulta address.*.
bounds locationBias.rectangle Renomeado; a estrutura mudou para objeto.
language languageCode Renomeado.
region regionCode Renomeado.
extra_computations Removido

Mudanças no campo de resposta

Campo v3 Campo v4 Observações
status, error_message Removido A v4 usa códigos de status HTTP e corpos de erro.
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText Renomeado.
results.geometry.location_type results.granularity Renomeado.
results.geometry.location results.location Nomes dos campos: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport Nomes dos campos: northeast/southwest -> high/low.
results.postcode_localities results.postalCodeLocalities Renomeado. Agora retornado para uma ou mais localidades (v3 obrigatório >1).
results.partial_match Removido
Nova results.addressComponents.languageCode Idioma do componente de endereço específico.
Nova results.bounds Limites explícitos usando high/low.
Nova results.place Nome do recurso para o lugar.
Nova results.postalAddress Objeto PostalAddress estruturado.

Migrar da geocodificação inversa v3

Se você usa a geocodificação inversa para transformar coordenadas em endereços, migre para o endpoint v4 Geocodificar inversamente um local, que aceita uma solicitação GET.

A API v4 muda nomes, estrutura e suporte para vários parâmetros. Recomendamos usar uma máscara de campo para especificar os campos que você quer retornar na resposta.

Mudanças nos parâmetros de solicitação

Parâmetro v3 Parâmetro v4 Observações
language languageCode Renomeado.
region regionCode Renomeado.
result_type types Renomeado; usa parâmetros de consulta repetidos.
location_type granularity Renomeado; usa parâmetros de consulta repetidos.
extra_computations Removido

Mudanças no campo de resposta

Campo v3 Campo v4 Observações
status, error_message Removido A v4 usa códigos de status HTTP e corpos de erro.
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText Renomeado.
results.geometry.location_type results.granularity Renomeado.
results.geometry.location results.location Nomes dos campos: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport Nomes dos campos: northeast/southwest -> high/low.
Nova results.addressComponents.languageCode Idioma do componente de endereço específico.
Nova results.bounds Limites explícitos usando high/low.
Nova results.place Nome do recurso para o lugar.
Nova results.postalAddress Objeto PostalAddress estruturado.

Migrar da geocodificação de lugares da v3

Se você usa place_id para receber o endereço de um ID de lugar específico com a API Geocoding v3, migre para o endpoint Place Geocoding v4, que aceita uma solicitação GET.

A API v4 muda nomes, estrutura e suporte para vários parâmetros. Recomendamos usar uma máscara de campo para especificar os campos que você quer retornar na resposta.

Mudanças nos parâmetros de solicitação

Parâmetro v3 Parâmetro v4 Observações
place_id Campo place no proto de solicitação O ID do lugar agora é fornecido como um parâmetro de caminho places/{place}, por exemplo: https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. Isso é mapeado para o campo "place" na solicitação subjacente.
language languageCode Renomeado.
region regionCode Renomeado.

Mudanças no campo de resposta

Campo v3 Campo v4 Observações
status, error_message Removido A v4 usa códigos de status HTTP e corpos de erro.
results (raiz) A v4 retorna um único objeto de resultado, não uma matriz results.
results.address_components.long_name / results.address_components.short_name addressComponents.longText / addressComponents.shortText Renomeado.
results.geometry.location_type granularity Renomeado.
results.geometry.location location Nomes dos campos: lat/lng -> latitude/longitude.
results.geometry.viewport viewport Nomes dos campos: northeast/southwest -> high/low.
results.postcode_localities postalCodeLocalities Renomeado. Agora retornado para uma ou mais localidades (v3 obrigatório >1).
Nova addressComponents.languageCode Idioma do componente de endereço específico.
Nova bounds Limites explícitos usando high/low.
Nova place Nome do recurso para o lugar.
Nova postalAddress Objeto PostalAddress estruturado.

Migrar de dados hiperlocais de geocodificação para destinos

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

  • Entradas
  • Pontos de navegação
  • Crie textos na estrutura de tópicos
  • 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 de lugar nesse campo pode ser de um lugar de qualquer tipo, não necessariamente apenas um edifício.

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.

Crie textos na estrutura de tópicos

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, você pode verificar se é um prédio com o campo placeView.structureType. Se o tipo de estrutura for BUILDING, você poderá extrair o contorno do 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 que representa 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 acessar as entradas, os pontos de navegação, os contornos dos edifícios e os 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/v4beta/geocode/destinations

Considerações sobre segurança

A API Geocoding v4 foi projetada como uma API entre servidores. Não há um caminho de migração direta para usuários de JavaScript da v3 para a v4. Chamar os métodos da v4 diretamente do JavaScript do lado do cliente (por exemplo, em um navegador) usando uma chave de API expõe sua chave de API a um alto risco de roubo e uso indevido.

As restrições de referenciador HTTP, embora úteis, não são proteção suficiente para endpoints de serviços da Web, já que podem ser facilmente ignoradas por invasores que falsificam o cabeçalho Referer nas solicitações.

A maneira recomendada de usar a API Geocoding v4 é pelo seu próprio servidor de back-end. O aplicativo cliente precisa fazer solicitações a esse servidor intermediário, que chama a API do Google de forma segura usando uma chave de API protegida (por exemplo, uma chave armazenada em uma variável de ambiente ou um gerenciador de secrets). Isso garante que sua chave de API nunca seja exposta no código do front-end.

Alternativas para necessidades do lado do cliente

Se você tiver necessidades do lado do cliente que exijam geocodificação, use uma das soluções atuais do lado do cliente: