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

Objetivo

Como desenvolvedor, você geralmente trabalha 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, desde a verificação do ID do cliente até a entrega e muito mais.

A API Address Validation é um produto da Plataforma Google Maps que você pode usar para validar um endereço. No entanto, ele processa apenas um endereço por vez. Neste documento, vamos examinar como usar a validação de endereço de alto volume em diferentes cenários, desde o teste da API até a 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.

testes

Muitas vezes, é recomendável executar milhares de endereços para testar a API Address Validation. Talvez você tenha os endereços em um arquivo com valores separados por vírgulas e queira validar a qualidade deles.

Validação única de endereços

Durante a integração à 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

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

• Talvez você tenha jobs programados para validar endereços e conseguir detalhes durante o dia, por exemplo, de inscrições de clientes, detalhes de pedidos e programações de entrega.
• Você pode receber despejos de dados contendo endereços de diferentes departamentos, por exemplo, de vendas a marketing. O novo departamento que recebe os endereços geralmente quer validá-los antes do uso.
• É possível coletar endereços durante pesquisas ou em várias promoções e posteriormente na atualização do sistema on-line. Você quer confirmar se os endereços estão corretos ao inseri-los no sistema.

Aprofundamento técnico

Para os fins deste documento, consideramos 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).
• Você pode armazenar sinalizações de validade em cache em endereços individuais em seu banco de dados.
• As sinalizações de validade são recuperadas da API Address Validation quando um cliente individual faz login.

Faça um teste:acesse o console do Google Cloud e ative a API Address Validation.

Cache para uso em produção

Observação: os elementos de resposta específicos descritos na seção a seguir podem ser armazenados por no máximo 30 dias consecutivos. Todos esses elementos de resposta PRECISAM ser excluídos após esse período.

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

Para o caso de uso da validação de endereço de volume, o armazenamento em cache de dados precisa seguir os Termos específicos de 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, solicite ao usuário 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 só poderão ser armazenados com o consentimento do usuário. Isso garante que o usuário saiba por que um determinado serviço está armazenando o endereço 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. Você sabe que vai armazenar em cache e processar o endereço para enviar um pacote.

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

Entender a resposta

Observação: também há um ótimo guia sobre Criar sua lógica de validação, que explica como interpretar a resposta.

Se a resposta da API Address Validation tiver os marcadores a seguir, você terá certeza de que o endereço de entrada tem qualidade de entrega:

• O marcador addressComplete no objeto Verdict é true,
• O validationGranularity no objeto Veredito é 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 apresentava baixa qualidade e é possível armazenar as sinalizações em cache no banco de dados para refletir isso. As flags em cache indicam que o endereço como um todo tem baixa qualidade, enquanto sinalizações mais detalhadas, como "Ortografia corrigida", 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, você pode chamar a API Address Validation com o endereço atual. A API Address Validation retornará o endereço corrigido, que pode ser exibido usando um prompt 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 comando

Observação: o que é headless? Um software capaz de funcionar em um dispositivo sem uma interface gráfica do usuário, como um script executado no lado do servidor ou na linha de comando. Vamos usar esse termo para descrever quando o software for usado sem uma GUI.

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 os dados que podem ser armazenados em cache.

Na seção a seguir, discutiremos um processo de duas etapas para cumprir os Termos de Serviço e implementar a validação de endereços de alto volume.

Etapa 1:

Na primeira etapa, analisaremos como implementar um script de validação de endereço de alto volume a partir de um pipeline de dados atual. Esse processo permitirá que você armazene campos específicos da resposta da API Address Validation em conformidade 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, é possível armazenar em cache os seguintes dados do addressComponent:

• confirmationLevel
• inferred
• spellCorrected
• replaced
• unexpected

Portanto, nesta etapa da implementação, armazenaremos em cache os campos mencionados acima no UserID.

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

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 apresentar esses endereços sinalizados ao usuário e obter o consentimento dele para corrigir o endereço armazenado.

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

1. Quando o usuário fizer login, verifique primeiro se você armazenou em cache alguma sinalização de validação no sistema.
2. Se houver sinalizações, apresente ao usuário uma IU para corrigir e atualizar o endereço.
3. É possível 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 retornará um formattedAddress.
5. É possível 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, armazene o formattedAddress em cache no banco de dados.

Observação: após a conclusão desse fluxo de trabalho, os validationFlags armazenados em cache precisam ser excluídos.

Conclusão

A validação de endereço de alto volume é um caso de uso comum que você provavelmente encontrará em muitos aplicativos. Neste documento, demonstraremos alguns cenários e um padrão de design sobre como implementar essa solução 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 o guia para começar a criar rapidamente com a Validação de Endereço de Alto Volume. 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 artigo Como melhorar a finalização de compras, a entrega e as operações com endereços confiáveis e assista ao webinar Como melhorar a finalização de compras, a entrega e as operações com a Address Validation .

Leitura adicional sugerida:

• Aplicativos de validação de endereço de alto volume
• Biblioteca Python no GitHub
• Confira a demonstração da validação de endereço

Colaboradores

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

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