Referência rápida da API Geocoding

A API Geocoding é um serviço da Web que converte endereços em coordenadas e IDs de lugar, e vice-versa. O método v4 SearchDestinations também retorna detalhes do destino, como entradas de edifícios, pontos de navegação, contornos de edifícios e terrenos e pontos de referência próximos.

API Geocoding: fatos importantes

  • Produto: API Geocoding
  • Categoria: lugares
  • Plataforma: serviço da Web (REST)
  • Executado em: servidor (código de back-end)
  • Estágio de lançamento: GA
  • Ciclo de vida: Ativo
  • Visão geral: Visão geral da API Geocoding

API Geocoding: quando usar

Use a API Geocoding quando:

  • Você precisa converter um endereço em coordenadas de latitude/longitude e um ID de lugar no seu servidor de back-end.
  • Você precisa de um endereço de exibição ou área político-administrativa (cidade, código postal) para coordenadas de GPS ou um ID de lugar conhecido.
  • Você precisa de entradas de edifícios, pontos de navegação roteáveis ou contornos de edifícios/terrenos para direcionar motoristas ou entregadores a um destino.
  • Você precisa resolver um destino dentro de um grande complexo (aeroporto, shopping, campus) em subdestinos ou pontos de referência próximos.

Não use a API Geocoding quando:

  • Você precisa de geocodificação do JavaScript do navegador do lado do cliente. Chamar a v4 com uma chave de API exposta é um risco de segurança. Use a API Maps JavaScript.
  • Você precisa calcular um trajeto ou um HEC até o destino geocodificado. Use a API Routes.
  • Você precisa de navegação guiada para um token de ponto de navegação em um app Android. Use o SDK do Navigation para Android.
  • Você precisa de navegação guiada para um token de ponto de navegação em um app iOS. Use o SDK do Navigation para iOS.

API Geocoding: configuração

API Geocoding: erros comuns

  • Problema: as solicitações SearchDestinations sem uma máscara de campo falham com um erro. Ao contrário de GeocodeAddress, GeocodeLocation e GeocodePlace, a máscara de campo é obrigatória. Correção: defina o cabeçalho X-Goog-FieldMask ou o parâmetro $fields em cada solicitação SearchDestinations. Consulte /maps/documentation/geocoding/choose-fields.
  • Problema: a v4 do GeocodeAddress não tem um filtro de componente rígido (v3 components=country:US). Os parâmetros estruturados de address.* são combinados em um único endereço e não filtram os resultados. O regionCode também não tem um padrão na v4 (o padrão da v3 era us). Correção: filtre o results no lado do cliente: faça a correspondência de regionCode em maiúsculas com postalAddress.regionCode; faça a correspondência de áreas administrativas de duas letras em maiúsculas com postalAddress.administrativeArea e administrative_area_level_n addressComponents (shortText); normalize a entrada e o postalAddress.postalCode (remova espaços/hífens e aplique regras de região). Consulte /maps/documentation/geocoding/geocoding-v4-migrate.
  • Problema: chamar a API Geocoding v4 diretamente do JavaScript do navegador expõe a chave de API. As restrições de referenciador HTTP podem ser contornadas falsificando o cabeçalho Referer. Correção: chame a v4 do seu próprio back-end com uma chave protegida ou use o serviço de geocodificação da API Maps JavaScript (back-end v3) para necessidades do lado do cliente. Consulte /maps/documentation/geocoding/geocoding-v4-migrate.
  • Problema: o SearchDestinations pode retornar resultados que não têm um endereço principal preciso, ao contrário da v3 e dos outros métodos da v4. Correção: defina placeFilter.addressability como PRIMARY quando precisar apenas de resultados com endereços principais precisos. Consulte /maps/documentation/geocoding/geocoding-v4-migrate.
  • Problema: o código escrito para a API Geocoding v3 não funciona nas respostas REST da v4, que usa nomes de campo em lowerCamelCase (addressComponents, não address_components), remove status e error_message e retorna um único objeto raiz de GeocodePlace em vez de uma matriz results. Correção: verifique os códigos de status HTTP e os corpos de erro nas chamadas REST da v4, leia os campos lowerCamelCase (addressComponents, postalAddress) e observe que as respostas do gRPC ainda usam snake_case. Consulte /maps/documentation/geocoding/geocoding-v4-migrate.

API Geocoding: recursos legados e descontinuados

  • Dados hiperlocais da API Geocoding v3 (extra_computations: BUILDING_AND_ENTRANCES, NAVIGATION_POINTS, GROUNDS; campos de resposta buildings.entrances, navigation_points, buildings.building_outlines, grounds): descontinuados desde 13/08/2025. Substituição: método SearchDestinations (POST /v4/geocode/destinations) da API Geocoding v4. Consulte o guia de migração.

O que você pode fazer com a API Geocoding

Consulte os guias vinculados abaixo para cada tarefa ou compare os produtos no Explorador de recursos.