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
- Serviço a ser ativado:
geocoding-backend.googleapis.com - Autenticação: chave de API, OAuth 2.0, conta de serviço
- Comece agora: configure a API Geocoding
- Referência: referência da API Geocoding
- Preços: uso e faturamento da API Geocoding
- Políticas: políticas da API Geocoding
- Notas da versão: notas da versão da API Geocoding
API Geocoding: produtos relacionados
- Geralmente usado com: API Routes, SDK de navegação para Android, SDK de navegação para iOS
API Geocoding: erros comuns
- Problema: as solicitações
SearchDestinationssem uma máscara de campo falham com um erro. Ao contrário deGeocodeAddress,GeocodeLocationeGeocodePlace, a máscara de campo é obrigatória. Correção: defina o cabeçalhoX-Goog-FieldMaskou o parâmetro$fieldsem cada solicitaçãoSearchDestinations. Consulte /maps/documentation/geocoding/choose-fields. - Problema: a v4 do
GeocodeAddressnão tem um filtro de componente rígido (v3components=country:US). Os parâmetros estruturados deaddress.*são combinados em um único endereço e não filtram os resultados. OregionCodetambém não tem um padrão na v4 (o padrão da v3 eraus). Correção: filtre oresultsno lado do cliente: faça a correspondência deregionCodeem maiúsculas compostalAddress.regionCode; faça a correspondência de áreas administrativas de duas letras em maiúsculas compostalAddress.administrativeAreaeadministrative_area_level_naddressComponents(shortText); normalize a entrada e opostalAddress.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
SearchDestinationspode 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: definaplaceFilter.addressabilitycomoPRIMARYquando 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ãoaddress_components), removestatuseerror_messagee retorna um único objeto raiz deGeocodePlaceem vez de uma matrizresults. 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 respostabuildings.entrances,navigation_points,buildings.building_outlines,grounds): descontinuados desde 13/08/2025. Substituição: métodoSearchDestinations(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.
- Retornar as coordenadas de latitude/longitude de um endereço (geocodificação).
- Retornar o endereço de um conjunto de coordenadas de latitude/longitude (geocodificação inversa).
- Restringir uma solicitação de geocodificação para retornar resultados em uma janela de visualização específica. Observação: na API Geocoding v4, locationBias prioriza os resultados na janela de visualização especificada, em vez de restringi-los estritamente.
- Restrinja uma solicitação de geocodificação ou geocodificação inversa para retornar apenas resultados em uma região, país ou código postal específico. Observação: na API Geocoding v4, regionCode prioriza os resultados de uma região CLDR especificada, em vez de restringi-los estritamente. Para filtragem de componentes legados da v3 por país ou código postal, consulte https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering.
- Restringir uma solicitação de geocodificação inversa para retornar apenas resultados de tipos de endereço específicos. Observação: na API Geocoding v4, o parâmetro types filtra os resultados de geocodificação reversa retornados por tipo de endereço após a pesquisa, em vez de restringir a pesquisa em si.
- Retornar informações sobre a proximidade de pontos de referência ou áreas de um endereço.
- Retornar informações sobre a proximidade de pontos de referência ou áreas para um conjunto de coordenadas de latitude/longitude.
- Retorna informações sobre a proximidade de pontos de referência ou áreas para um identificador de lugar do Google.
- Retorna o endereço de um identificador de lugar do Google.
- Retornar as coordenadas de latitude/longitude do contorno de um edifício para um endereço.
- Retornar as coordenadas de latitude/longitude do contorno de um edifício para um conjunto de coordenadas de latitude/longitude.
- Retornar as coordenadas de latitude/longitude do contorno de um edifício para um identificador de lugar do Google.
- Retornar as coordenadas de latitude/longitude da entrada de um edifício para um endereço.
- Retornar as coordenadas de latitude/longitude da entrada de um edifício para um conjunto de coordenadas de latitude/longitude.
- Retornar as coordenadas de latitude/longitude da entrada de um edifício para um identificador de lugar do Google.