Migrar da API Geocoding v3 para a v4

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 serão aplicáveis ao uso dos Serviços. A funcionalidade varia de acordo com a região. Saiba mais.

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, faça o mesmo nas novas APIs v4. Não há um caminho de migração para usuários do JavaScript.

Observação:durante o pré-lançamento, os métodos da API Geocoding v4 são limitados a 25 consultas por segundo (QPS). Para informações sobre como solicitar uma cota maior, consulte Ver e gerenciar cotas e selecione API Geocoding como o serviço.

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.

Aviso: em todos os endpoints da v4, os nomes dos campos são formatados usando lower camel case (por exemplo, addressComponents), ao contrário dos endpoints da v3, que usavam snake case (por exemplo, address_components). As respostas de RPC continuam usando snake case na v4, assim como na v3.

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 necessá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.

Aviso: em todos os endpoints da v4, os nomes dos campos são formatados usando lower camel case (por exemplo, addressComponents), ao contrário dos endpoints da v3, que usavam snake case (por exemplo, address_components). As respostas de RPC continuam usando snake case na v4, assim como na v3.

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.

Aviso: em todos os endpoints da v4, os nomes dos campos são formatados usando lower camel case (por exemplo, addressComponents), ao contrário dos endpoints da v3, que usavam snake case (por exemplo, address_components). As respostas de RPC continuam usando snake case na v4, assim como na v3.

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 necessá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.

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, "5th Ave".
• 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.

Observação: você só quer o polígono de um edifício em um determinado local? É possível usar o parâmetro placeFilter na solicitação para restringir os resultados. Para retornar apenas resultados de construção, defina structureType como "BUILDING" em placeFilter. Se a prioridade for receber um polígono (mesmo para locais sem endereços precisos), defina addressability como "ANY" em placeFilter para retornar o polígono mais preciso disponível.

Exemplo

{
  "locationQuery": {
    "location": {
      "latitude": 37.4224,
      "longitude": -122.0841
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "ANY"
    }
  }
}
  

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/v4alpha/geocode/destinations