Use a API Address Validation para processar endereços com alto volume

Objetivo

Como desenvolvedor, você costuma trabalhar com conjuntos de dados que contêm endereços de clientes que podem não ser de boa qualidade. É preciso garantir que os endereços estejam corretos para casos de uso que vão desde a verificação de ID do cliente até a entrega, entre outros.

A API Address Validation é um produto da Plataforma Google Maps que pode ser usado para validar um endereço. No entanto, ele só processa um endereço por vez. Neste documento, vamos analisar como usar a validação de endereço de alto volume em diferentes cenários, desde testes de API até validação de endereço única e recorrente.

Casos de uso

Agora vamos entender os casos de uso em que a Validação de endereço de alto volume é útil.

Teste

Muitas vezes, você quer testar a API Address Validation executando milhares de endereços. Talvez você tenha os endereços em um arquivo de valores separados por vírgula e queira validar a qualidade deles.

Validação única de endereços

Ao integrar a API Address Validation, você quer validar seu banco de dados de endereços atual com o banco de dados de usuários.

Validação recorrente de endereços

Há vários cenários que exigem a validação recorrente de endereços:

• Você pode ter jobs programados para validar endereços com detalhes capturados durante o dia, por exemplo, de inscrições de clientes, detalhes de pedidos, horários de entrega.
• Você pode receber despejos de dados com endereços de diferentes departamentos, por exemplo, de vendas e marketing. O novo departamento que recebe os endereços geralmente quer validá-los antes de usar.
• Você pode coletar endereços durante pesquisas ou várias promoções e depois atualizar no sistema on-line. Você quer validar se os endereços estão corretos ao inseri-los no sistema.

Aprofundamento técnico

Para os fins deste documento, presumimos que:

• Você está chamando a API Address Validation com endereços de um banco de dados de clientes (ou seja, um banco de dados com detalhes de clientes).
• É possível armazenar em cache flags de validade em relação a endereços individuais no seu banco de dados.
• As flags de validade são recuperadas da API Address Validation quando um cliente individual faz login.

Cache para uso em produção

Ao usar a API Address Validation, muitas vezes é necessário armazenar em cache alguma parte da resposta da chamada de API. Embora nossos Termos de Serviço limitem quais dados podem ser armazenados em cache, qualquer dado que possa ser armazenado em cache da API Address Validation precisa ser armazenado em cache em uma conta de usuário. Isso significa que, no banco de dados, o endereço ou os metadados de endereço precisam ser armazenados em cache com o endereço de e-mail ou outro ID principal de um usuário.

Para o caso de uso de validação de endereço de alto volume, o armazenamento em cache de dados precisa seguir os Termos específicos do serviço da API Address Validation, conforme descrito na seção 11.3. Com base nessas informações, você poderá determinar se o endereço de um usuário é inválido. Nesse caso, peça um endereço corrigido na próxima interação com seu aplicativo.

• Dados do objeto AddressComponent
  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

Se você quiser armazenar em cache qualquer informação sobre o endereço real, esses dados deverão ser armazenados em cache apenas com o consentimento do usuário. Isso garante que o usuário saiba por que um serviço específico está armazenando o endereço dele e concorde com os termos de compartilhamento.

Um exemplo de consentimento do usuário seria a interação direta com um formulário de endereço de e-commerce em uma página de finalização da compra. Entende-se que você vai armazenar em cache e processar o endereço para fins de envio de um pacote.

Com o consentimento do usuário, é possível armazenar em cache formattedAddress e outros componentes principais da resposta. No entanto, em um cenário sem interface, um usuário não pode dar consentimento, já que a validação de endereço está acontecendo no back-end. Portanto, é possível armazenar em cache informações muito limitadas nesse cenário sem interface.

Entender a resposta

Se a resposta da API Address Validation contiver os seguintes marcadores, você poderá ter certeza de que o endereço de entrada é de qualidade para entrega:

• O marcador addressComplete no objeto Verdict é true.
• O validationGranularity no objeto Verdict é PREMISE ou SUB_PREMISE.
• Nenhum dos AddressComponent está marcado como:
  • Inferred(Observação: inferred=truepode acontecer quando addressComplete=true)
  • spellCorrected
  • replaced
  • unexpected e
• confirmationLevel: o nível de confirmação no AddressComponent está definido comoCONFIRMEDouUNCONFIRMED_BUT_PLAUSIBLE

Se a resposta da API não contiver os marcadores acima, o endereço de entrada provavelmente era de baixa qualidade, e você pode armazenar em cache flags no seu banco de dados para refletir isso. As flags armazenadas em cache indicam que o endereço como um todo é de baixa qualidade, enquanto flags mais detalhadas, como "Correção ortográfica", indicam o tipo específico de problema de qualidade do endereço. Na próxima interação do cliente com um endereço sinalizado como de baixa qualidade, chame a API Address Validation com o endereço atual. A API Address Validation vai retornar o endereço corrigido, que você pode mostrar usando um comando da interface. Depois que o cliente aceita o endereço formatado, você pode armazenar em cache o seguinte da resposta:

• formattedAddress
• postalAddress
• addressComponent componentNamesou
• UspsData standardizedAddress

Implementar uma validação de endereço sem interface

Com base na discussão acima:

• Muitas vezes, é necessário armazenar em cache alguma parte da resposta da API Address Validation por motivos comerciais.
• No entanto, os Termos de Serviço da Plataforma Google Maps restringem quais dados podem ser armazenados em cache.

Na seção a seguir, vamos discutir um processo de duas etapas sobre como obedecer aos Termos de Serviço e implementar a validação de endereços de alto volume.

Etapa 1:

Na primeira etapa, vamos analisar como implementar um script de validação de endereço de alto volume de um pipeline de dados atual. Esse processo permite armazenar campos específicos da resposta da API Address Validation de acordo com os Termos de Serviço.

Diagrama A:o diagrama a seguir mostra como um pipeline de dados pode ser aprimorado com uma lógica de validação de endereço de alto volume.

De acordo com os Termos de Serviço, você pode armazenar em cache os seguintes dados do addressComponent:

• confirmationLevel
• inferred
• spellCorrected
• replaced
• unexpected

Assim, durante esta etapa da implementação, vamos armazenar em cache os campos mencionados acima em relação ao UserID.

Para mais informações, consulte detalhes sobre a estrutura de dados real.

Etapa 2:

Na etapa 1, coletamos feedback de que alguns endereços no conjunto de dados de entrada podem não ser de alta qualidade. Na próxima etapa, vamos pegar esses endereços sinalizados e apresentá-los ao usuário para que ele autorize a correção do endereço armazenado.

Diagrama B: este diagrama mostra como seria uma integração de ponta a ponta do fluxo de consentimento do usuário:

1. Quando o usuário fizer login, primeiro verifique se você armazenou em cache alguma flag de validação no seu sistema.
2. Se houver flags, apresente ao usuário uma interface para corrigir e atualizar o endereço.
3. Você pode chamar a API Address Validation novamente com o endereço atualizado ou em cache e apresentar o endereço corrigido ao usuário para confirmação.
4. Se o endereço for de boa qualidade, a API Address Validation vai retornar um formattedAddress.
5. Você pode apresentar esse endereço ao usuário se as correções tiverem sido feitas ou aceitar silenciosamente se não houver correções.
6. Depois que o usuário aceitar, você poderá armazenar em cache o formattedAddress no banco de dados.

Conclusão

A validação de endereços de alto volume é um caso de uso comum que você provavelmente vai encontrar em muitos aplicativos. Este documento tenta demonstrar alguns cenários e um padrão de design sobre como implementar uma solução desse tipo em conformidade com os Termos de Serviço da Plataforma Google Maps.

Também escrevemos uma implementação de referência da validação de endereços de alto volume como uma biblioteca de código aberto no GitHub. Confira para começar a criar com a High Volume Address Validation rapidamente. Consulte também o artigo sobre padrões de design para saber como usar a biblioteca em diferentes cenários.

Próximas etapas

Baixe o Whitepaper "Melhore a finalização da compra, o envio e as operações com endereços confiáveis" e assista ao Webinar "Melhorar a finalização da compra, o envio e as operações com a validação de endereços ".

Leitura adicional sugerida:

• Aplicações da validação de endereço de alto volume
• Biblioteca Python no GitHub
• Confira a demonstração da Address Validation

Colaboradores

O Google mantém este artigo. Os colaboradores a seguir escreveram o texto original.
Principais autores:

Henrik Valve | Engenheiro de soluções
Thomas Anglaret | Engenheiro de soluções
Sarthak Ganguly | Engenheiro de soluções