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. É necessário garantir que os endereços estejam corretos para casos de uso que vão desde a confirmação de identidade com documento do cliente até a entrega e muito mais.

A Address Validation API é um produto da Plataforma Google Maps que pode ser usado para validar um endereço. No entanto, ela 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 em relação ao banco de dados do usuário.

Validação recorrente de endereços

Vários cenários exigem a validação de endereços de forma recorrente:

• Você pode ter jobs programados para validar endereços de detalhes capturados durante o dia, por exemplo, de inscrições de clientes, detalhes de pedidos, programações de entrega.
• Você pode receber despejos de dados que contêm endereços de diferentes departamentos, por exemplo, de vendas a 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, mais tarde, atualizar no sistema on-line. Você gostaria de validar se os endereços estão corretos ao inseri-los no sistema.

Aprofundamento técnico

Para 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 do cliente).
• É possível armazenar em cache flags de validade em endereços individuais no seu banco de dados.
• Os flags de validade são recuperados da API Address Validation quando um cliente individual faz login.

Cache para uso de produção

Ao usar a API Address Validation, muitas vezes você quer armazenar em cache parte da resposta da chamada de API. Embora nossos Termos de Serviço limitem quais dados podem ser armazenados em cache, todos os dados que podem ser armazenados em cache da API Address Validation precisam ser armazenados em cache em uma conta de usuário. Isso significa que, no banco de dados, o endereço ou os metadados do endereço precisam ser armazenados em cache no endereço de e-mail ou em outro ID principal de um usuário.

Para o caso de uso de validação de endereço de alto volume, o armazenamento de dados em cache precisa seguir os Termos Específicos do Serviço da API Address Validation, descritos 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, você vai pedir ao usuário um endereço corrigido durante a próxima interação com o 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 só poderão ser armazenados em cache com o consentimento do usuário. Isso garante que o usuário esteja ciente do motivo pelo qual um serviço específico está armazenando o endereço dele e que ele concorda com os termos de compartilhamento do endereço.

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. Há um entendimento de 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 entregável:

• 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, é provável que o endereço de entrada seja de baixa qualidade, e você poderá armazenar flags em cache no seu banco de dados para refletir isso. Os flags armazenados em cache indicam que o endereço como um todo é de baixa qualidade, enquanto flags mais detalhados, como "Corrigido ortograficamente", indicam o tipo específico de problema de qualidade do endereço. Na próxima interação do cliente com um endereço marcado como de baixa qualidade, você poderá chamar 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 aviso da interface. Depois que o cliente aceitar o endereço formatado, você poderá 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 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ço 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 uma maneira compatível 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 Address Validation de alto volume.

De acordo com os Termos de Serviço, é possível armazenar em cache os seguintes dados do addressComponent:

• confirmationLevel
• inferred
• spellCorrected
• replaced
• unexpected

Assim, durante essa 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 e receber o consentimento dele para corrigir o endereço armazenado.

Diagrama B: este diagrama mostra como uma integração completa do fluxo de consentimento do usuário pode ser:

1. Quando o usuário fizer login, primeiro verifique se você armazenou em cache algum 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 armazenado 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 o formattedAddress em cache no banco de dados.

Conclusão

A validação de endereço de alto volume é um caso de uso comum que você provavelmente 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ço de alto volume como uma biblioteca de código aberto no GitHub. Confira para começar a criar com a Address Validation de alto volume rapidamente. Acesse também o artigo sobre padrões de design de como usar a biblioteca em diferentes cenários.

Próximas etapas

Faça o download do white paper Melhorar a finalização de compra, a entrega e as operações com endereços confiáveis e assista ao webinar Melhorar a finalização de compra, a entrega e as operações com a validação de endereço .

Leituras sugeridas:

• Aplicações da Address Validation de alto volume
• Biblioteca Python no GitHub (link em inglês)
• Confira a demonstração da validação de endereço

Colaboradores

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

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