Criar recursos de validação de local usando a Plataforma Google Maps

Objetivo

Muitas vezes, é necessário validar a localização de um lugar. Existem alguns serviços diferentes na Plataforma Google Maps que podem ajudar nesse caso de uso. Este documento ajuda você a escolher entre os dois serviços principais de validação de local: a API Address Validation e a API Geocoding.

A API Address Validation é uma oferta da Plataforma Google Maps que ajuda os clientes a validar se um endereço é preciso ou não.

Geocoding com a API Geocoding é o processo de converter endereços em coordenadas geográficas, que você pode usar para colocar marcadores em um mapa ou em uma posição nele.

Uma visão geral das diferenças entre a Address Validation e a API Geocoding pode ser encontrada aqui.

Quando escolher a API Address Validation ou a API Geocoding

Address-Validation-vs-Geocoding

Observações sobre o fluxograma acima:

  • O caso de uso de interação do usuário se refere a quando um usuário está presente para interagir com os resultados.
  • O Places Autocomplete é uma API JavaScript, ideal para integração com interfaces do usuário.
  • Talvez você esteja ciente dos problemas de qualidade de dados nos seus endereços atuais. Portanto, embora você queira apenas geocódigos, é aconselhável executar esses locais com a API Address Validation para corrigir os conjuntos de dados.

Há muitas situações em que você pode escolher, com base na árvore de decisão acima, usar um produto em vez do outro. Mas outras situações podem envolver o uso dos dois produtos para atingir seus objetivos.

Use a API Address Validation em vez da API Geocoding quando:

  • Há uma grande chance de haver dados questionáveis ou em que a coleta de um endereço incorreto tem um impacto negativo. Isso ocorre porque a API Address Validation fornece mais feedback sobre por que uma entrada não recebeu um resultado de alta precisão.
  • Você precisa corrigir entradas do usuário (por exemplo, erros ortográficos ou campos ausentes), o que aumenta a probabilidade de um resultado preciso na saída.
  • A região de destino retorna mais metadados da API Address Validation em comparação com a API Geocoding, por exemplo, a classificação do tipo de edifício como residencial x comercial.

Use a API Geocoding em vez da API Address Validation quando:

  • Seu objetivo principal é recuperar a localização de um endereço, e a precisão de endereços individuais pode não ser essencial.
    • Por exemplo, para gerar um mapa de calor a partir de um grande conjunto de dados.
  • Você precisa de uma solução global, e a API Address Validation não está disponível em todas as regiões de destino.

Confira a seguir alguns exemplos que demonstram os recursos da API Address Validation em comparação com a API Geocoding.

Exemplo de endereço inválido

1 Fake St, Mountain View, CA 94043, EUA

A API Address Validation divide essa entrada em componentes de endereço individuais (rua, cidade, estado etc.). Também é possível fornecer feedback detalhado sobre por que o endereço não é válido até o nível PREMISE.

A Fake St não existe em Mountain View, CA, e a API Address Validation reflete isso nos detalhes do nível do componente retornado:

{
  "componentName": {
    "text": "Fake St",
    "languageCode": "en"
   },
   "componentType": "route",
   "confirmationLevel":"UNCONFIRMED_BUT_PLAUSIBLE"
 }

A propriedade importante a ser inspecionada nesse caso é confirmationLevel. Ao retornar UNCONFIRMED_BUT_PLAUSIBLE em relação à Fake St, a API determinou que seria possível que uma rua tivesse esse nome como nome, mas que não corresponde aos dados de endereço de suporte.

Usando o resultado da API como feedback, pode-se deduzir que o componente de rua dessa entrada (Fake St) está com falha.

Usando o mesmo endereço com a Geocoding API, é possível fazer uma correspondência com “Califórnia”, como você pode ver na captura de tela da ferramenta de geocodificação, que você pode testar aqui:

alt_text

No entanto, o resultado é um geocódigo de todo o estado, com feedback mínimo sobre quais componentes da entrada estavam potencialmente com falhas.

Exemplo de erro ortográfico

76 Buckingamm Palace Road, Londn, SW1W 9TQ, Reino Unido

O endereço acima contém alguns erros de ortografia, um no nome da rua e outro na localidade.

Tanto a Address Validation quanto a Geocoding API são capazes de corrigir esses erros e alcançar o resultado de 76 Buckingham Palace Road, Londres, SW1W 9TQ. No entanto, a API Address Validation pode fornecer mais informações sobre o processo.

Veja um dos componentes de endereço com erro de digitação na entrada:

{
  "componentName": {
    "text": "Buckingham Palace Road",
    "languageCode": "en"
        },
        "componentType": "route",
        "confirmationLevel": "CONFIRMED",
        "spellCorrected": true
     }
}

A API Address Validation retorna uma sinalização para indicar que uma correção foi feita no campo. A lógica de negócios pode ser implementada nessa flag para verificar novamente a correção com o provedor de dados, como um cliente em uma finalização de compra de e-commerce.

Dados ausentes e exemplo de erro ortográfico

Bollschestraße 86, 12587, Alemanha

O endereço acima apresenta um erro de ortografia no nome da rua e não consta a cidade (localidade) de Berlim.

A API Address Validation pode corrigir esses dois erros e retorna um geocódigo de nível PREMISE e um endereço que é verificado no nível do PREMISE:

Bölschestraße 86, 12587 Berlin, DE

A API Geocoding não consegue resolver os erros de entrada nesse caso e retorna um resultado de ZERO_RESULTS.

Exemplo de metadados de endereço adicional

111 8th Avenue Ste 123, Nova York, NY 10011-5201, EUA

Este endereço está correto, exceto pelo número da unidade (Estão 123), que não existe no edifício.

A API Address Validation pode validar o endereço para PREMISE (8a Avenida, 111) e fornecer alguns metadados sobre a propriedade, incluindo que se trata de um endereço comercial

local:

"business": true

Além disso, o valor dpvConfirmation retornado como parte de uspsData na resposta é S:

"dpvConfirmation": "S"

Um valor dpvConfirmation de S indica que o endereço está validado no nível PREMISE, mas o número da unidade fornecido na entrada não está associado a esse endereço.

A API Geocoding não pode fornecer essas informações.

Noções básicas sobre a resposta da API Geocoding

Visão geral

Se você usa a API Geocoding, o resultado do geocódigo contém várias pistas na resposta que podem ser usadas para entender os detalhes do endereço fornecido.

A API Geocoding funciona resolvendo os componentes de endereço em uma hierarquia.

Por **exemplo, 123 Example Street, Chicago, 60007, USA é resolvido na seguinte ordem:

/ Example Street/ Chicago/ 60007/ USA serão avaliados nessa ordem. A primeira correspondência nesse caso é Chicago e, mais especificamente, o CEP 60007. Portanto, ele retorna o seguinte Place_id para esse CEP:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

A API Geocode contém as seguintes informações na resposta:

        "partial_match": true,
           "place_id": "ChIJwRKzf8ixD4gRHiXqucwr_HQ",
           "types": [
               "postal_code"
           ]

A API Geocoding pode confirmar a que tipo de lugar este endereço pertence. Uma lista de endereços types retornados pela API Geocoding pode ser encontrada aqui.

Se nenhum dos componentes da entrada for resolvido, a API retornará:

{
   "results": [],
   "status": "ZERO_RESULTS"
}

Fazer uma solicitação apenas com o endereço e sem o número da casa retorna um resultado no formulário:

"types": [
  "route"
]

Isso significa que a API Geocoding não consegue encontrar ou corresponder um número de rua.

Observação: para saber se um endereço existe, verifique se algum dos parâmetros (como types ou partial_match, results, status)) está definido na resposta da API Geocoding. Isso aumenta gradualmente o nível de confiança de que um endereço existe, mas não o torna 100% preciso. É por isso que precisamos da API Address Validation.

Você pode usar as técnicas acima para aumentar a confiança na precisão do endereço apenas com uma resposta da API Geocoding. No entanto, ao contrário de um resultado da API Address Validation, a API Geocoding não vai retornar feedback exato para determinar a precisão do resultado.

Tipo de local

Para entender esta seção corretamente, é preciso entender os diferentes tipos de local que podem ser retornados de uma resposta da API Geocoding:

  • ROOFTOP indica que o resultado retornado é um geocódigo preciso, para o qual temos informações de local que incluem o endereço.
  • RANGE_INTERPOLATED indica que o resultado retornado reflete uma aproximação (geralmente em uma via) interpolada entre dois pontos precisos (como interseções). Resultados interpolados geralmente são retornados quando códigos geográficos de rooftop não estão disponíveis para um endereço.
  • GEOMETRIC_CENTER indica que o resultado retornado é o centro geométrico de um resultado, como uma polilinha (por exemplo, uma rua) ou um polígono (região).
  • APPROXIMATE indica que o resultado retornado não é nenhuma das opções acima.

Se uma API Geocoding retorna um location_type de ROOFTOP ou RANGE_INTERPOLATED, isso não significa necessariamente que o endereço existe. Da mesma forma, se uma API Geocoding retornar com a flag partial_match definida como true, talvez esse ainda seja o resultado certo para você.

Esse tipo de correspondência falsa é um problema muito difícil de resolver com a API Geocoding. No mínimo, você pode considerar a implementação de alguma validação básica de pós-processamento no país e na localidade da solicitação / resposta. Melhor ainda, compare os endereços reais em busca de erros de ortografia e/ou endereços incompletos.

Observação: se você decidir usar a API Geocoding, é recomendável realizar verificações de qualidade de dados regularmente entre a solicitação inicial e a resposta da API Geocoding.

Correspondência parcial e falsa

Se um endereço for uma correspondência parcial, o que significa que a API Geocoding não conseguiu identificar com precisão o endereço, a resposta vai conter:

"partial_match": true,
"types": [
           "locality",
           "political"
         ]

Ainda mais importante do que os tipos de local acima é considerar quando partial_match = true estiver na resposta. partial_match indica que a API Geocoding não retornou uma correspondência exata para a solicitação original, mas conseguiu associar parte do endereço solicitado.

Convém examinar a solicitação original de um endereço incompleto. Correspondências parciais ocorrem com mais frequência para endereços que não existem na localidade especificada na solicitação. Elas também podem ser retornadas quando uma solicitação corresponde a dois ou mais locais na mesma localidade.

Por exemplo, "21 Henr St, Bristol, UK" retorna uma correspondência parcial para Henry Street e Henrietta Street. Se uma solicitação incluir um componente de endereço com um erro ortográfico, a API Geocoding poderá sugerir um endereço alternativo. Sugestões acionadas dessa forma não serão marcadas como correspondência parcial.

Endereços sintéticos

A API Geocoding pode retornar locais para "sintético" endereços que não existem como locais precisos no banco de dados do Google.

Nessas situações, o objeto de resposta geralmente contém um ID de lugar longo e a seguinte propriedade: geometry.location_type=APPROXIMATE.

Se você encontrar esses indicadores na resposta, marque o endereço de entrada como inválido e tente revalidá-lo de outra forma.

Observação: este é outro exemplo em que, com a API Address Validation, você recebe feedback direto quando um endereço não existe.

Noções básicas sobre a resposta da API Address Validation

Já existe uma ótima documentação sobre como entender as respostas da API Address Validation, então não vamos entrar em mais detalhes aqui.

Práticas recomendadas

Como especificar uma região geográfica

Ao fazer chamadas para as APIs Address Validation ou Geocoding, é uma prática recomendada tentar limitar a região geográfica em que esse endereço será pesquisado. As duas APIs implementam isso de duas maneiras diferentes:

  • API Geocoding: polarização de região

    Se você souber que os geocódigos estarão dentro de um determinado país, terá resultados muito melhores usando a polarização de região. Por exemplo, se você estiver geocodificando no Canadá, recomendamos adicionar &region=ca às suas solicitações para direcionar para o Canadá. A polarização de região prioriza apenas resultados dentro dessa região. Você ainda pode receber resultados fora dessa região.

  • API Address Validation: código regional

    Da mesma forma, a API Address Validation produz resultados mais precisos quando um código ISO2 é transmitido na solicitação usando o campo regionCode.

Armazenar IDs de lugar

Se quiser armazenar informações da Plataforma Google Maps sobre o local para solicitações futuras, armazene o ID de lugar indefinidamente no seu banco de dados como um atributo do local. Você só precisa fazer uma solicitação do Find Place uma vez para cada ID de lugar. Também é possível pesquisar o ID de lugar sempre que um usuário solicitar detalhes da transação.

Para garantir que você sempre tenha as informações mais atualizadas, atualize os IDs de lugar a cada 12 meses usando uma solicitação do Place Details com o parâmetro place_id.

Observação: consulte também o guia de práticas recomendadas sobre geocodificação.

Conclusão

Este documento descreve as principais diferenças entre as APIs Address Validation e Geocoding. Em resumo, considere usar a API Address Validation quando:

  • É necessário um endereço de correspondência correto, principalmente para fins de entrega.
  • Sabe-se que os dados de entrada são de má qualidade. A API Address Validation é mais tolerante a erros de entrada, destaca componentes de endereço não verificáveis e faz correções nos dados de entrada.
  • São necessárias mais informações para um endereço, como residencial ou comercial (disponível em algumas regiões).

Próximas etapas

Faça o download do artigo Melhore a finalização da compra, a entrega e as operações com endereços confiáveis e confira o webinar Como melhorar a finalização de compras, a entrega e as operações com a Address Validation .

Leitura adicional sugerida:

Colaboradores

O Google mantém este artigo. Os colaboradores a seguir o escreveram originalmente.

Autores principais:

Válvula Henrik | Engenheiro de soluções

Thomas Anglaret | Engenheiro de soluções

Sarthak Ganguly | Engenheiro de soluções