Geocodificação com maior precisão

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. Os produtos e recursos em pré-GA são cobertos 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 valer para o uso dos serviços. A funcionalidade varia de acordo com a região. Saiba mais.

Os métodos GeocodeAddress e SearchDestinations aceitam um parâmetro effort opcional que permite controlar o equilíbrio entre a latência de resposta e a precisão da resolução de endereços.

Embora a geocodificação padrão processe endereços postais bem formatados com latência de menos de um segundo, as entradas reais geralmente são incompletas, informais ou complexas (por exemplo, "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai" ou "where the warriors play, sf"). Ao configurar um nível de effort mais alto, você pode instruir a API Geocoding a aplicar raciocínio estendido e desambiguação para resolver endereços difíceis.

Importante :esse recurso está disponível no canal v4alpha. Mais informações sobre os canais de fase de lançamento.

Níveis de esforço

Especifique um dos seguintes valores para o parâmetro effort:

Nível de esforço	Descrição	Latência típica	Casos de uso recomendados
EFFORT_UNSPECIFIED	Valor padrão. Comportamento igual ao do esforço LOW.	Subsegundo	Geocodificação padrão.
LOW	Otimiza os tempos de resposta mais rápidos. Não realiza pesquisa estendida ou desambiguação para endereços difíceis.	Subsegundo	Pesquisa interativa em tempo real, validação de endereços padrão de alto volume.
MEDIUM	Equilibra velocidade e precisão. A maioria das solicitações retorna com baixa latência padrão. Para endereços ambíguos ou difíceis, o serviço aplica um processamento adicional para melhorar a precisão, o que pode levar alguns segundos.	Menos de um segundo para endereços padrão; até alguns segundos (≤ 4 segundos) para endereços ambíguos	Fluxos de trabalho interativos do usuário (como confirmação de endereço na finalização da compra), em que os usuários podem tolerar uma breve pausa.
HIGH	Maximiza a precisão da resolução de endereços incompletos, informais ou complexos. O tempo de resposta pode ser bem maior.	Até 20 segundos para endereços complexos	Processamento em segundo plano, definição de geocódigos em lote, despacho de logística ou refinamento de endereço assíncrono após o pagamento.

Observação: os níveis de esforço MEDIUM e HIGH usam modelos do Gemini para processar e resolver ambiguidades em endereços complexos. As respostas são resolvidas usando IA e podem conter erros.

Exemplos de solicitação

Pesquisar destinos (SearchDestinations)

Inclua o campo effort no corpo da solicitação JSON da sua solicitação POST para https://geocode.googleapis.com/v4alpha/geocode/destinations. O parâmetro effort afeta principalmente a resolução de addressQuery:

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
  },
  "effort": "HIGH"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations

Geocodificar um endereço (GeocodeAddress)

Transmita o parâmetro effort como um parâmetro de consulta de URL na solicitação GET para o endpoint /v4alpha/:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4alpha/geocode/address/where+the+warriors+play,+sf?effort=MEDIUM"

Como reduzir o impacto da latência

Ao usar o esforço MEDIUM ou HIGH no aplicativo, enviar uma solicitação de passagem única é a integração mais simples, mas as solicitações nesses modos podem gerar uma latência maior, o que pode atrasar fluxos de trabalho síncronos, voltados ao usuário e sensíveis à latência.

Para reduzir esse impacto da latência nos fluxos interativos do usuário (como finalização de compra ou reserva), use um fluxo de trabalho de várias etapas:

1. Etapa 1 (interativa): envie uma solicitação síncrona com effort=LOW (ou padrão) para validar o endereço imediatamente com latência de menos de um segundo.
2. Etapa 2 (segundo plano): envie uma solicitação de acompanhamento assíncrona com effort=MEDIUM ou effort=HIGH (por exemplo, após o pagamento ou antes do envio) para resolver endereços complexos em coordenadas de alta precisão, entradas e pontos de navegação sem bloquear o usuário.

Limites de uso

Durante a fase de lançamento experimental (v4alpha), as solicitações com effort definido como MEDIUM ou HIGH estão sujeitas a limites de taxa mais rígidos do que as solicitações padrão (LOW). Se o aplicativo exceder esses limites de taxa, a API vai retornar um erro RESOURCE_EXHAUSTED (HTTP 429). Se você encontrar erros HTTP 429 ou precisar de uma cota maior para seu caso de uso, entre em contato pelo canal de feedback.

Feedback

Este é um recurso experimental da API Geocoding. Envie seu feedback para [e-mail].