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

Objetivo

Como desenvolvedor, você geralmente trabalha com conjuntos de dados contendo endereços de clientes que podem não ser de boa qualidade. Você precisa garantir que os endereços estejam corretos para casos de uso que variam 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, analisaremos como usar a validação de endereço de alto volume em diferentes cenários, desde o teste de 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, você quer testar a API Address Validation executando milhares de endereços. 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

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

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

• Você pode ter tarefas agendadas para validar endereços para detalhes capturados durante o dia, por exemplo, de inscrições de clientes, detalhes do pedido, programações de entrega.
• Você pode receber despejos de dados com endereços de diferentes departamentos, por exemplo, de vendas a marketing. O novo departamento que vai receber os endereços geralmente quer validá-los antes de usá-los.
• É possível coletar endereços durante pesquisas ou em várias promoções e, depois, em atualizações no sistema on-line. Você quer confirmar se os endereços estão corretos ao inseri-los no sistema.

Aprofundamento técnico

Neste documento, pressupomos 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 flags de validade em cache em endereços individuais no 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 agora: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 30 dias.

Ao usar a API Address Validation, normalmente você quer armazenar em cache alguma parte da resposta da chamada de API. Nossos Termos de Serviço limitam quais dados podem ser armazenados em cache, mas todos aqueles 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 de um usuário ou outro ID principal.

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 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 pode ser inválido. Nesse caso, você vai solicitar um endereço corrigido ao usuário na próxima interação com o aplicativo.

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

Se você quiser armazenar informações sobre o endereço real em cache, 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 aceita 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 comércio eletrônico em uma página de finalização de compra. Há o entendimento de que você armazenará em cache e processará o endereço para fins de envio de um pacote.

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

Entender a resposta

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

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

• O marcador addressComplete no objeto Veredito é 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 é definido comoCONFIRMEDouUNCONFIRMED_BUT_PLAUSIBLE

Se a resposta da API não contiver os marcadores acima, é provável que o endereço de entrada tenha baixa qualidade, e você pode armazenar sinalizações em cache no seu banco de dados para refletir isso. As sinalizações em cache indicam que o endereço, como um todo, é de 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, chame a API Address Validation com o endereço atual. A API Address Validation retornará o endereço corrigido, que pode ser exibido em uma solicitação 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 headless

Observação: o que é headless? Um software capaz de trabalhar em um dispositivo sem uma interface gráfica do usuário, como um script do lado do servidor ou executado por linha de comando. Usaremos esse termo para descrever quando o software é 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 quais dados podem ser armazenados em cache.

Na seção a seguir, vamos discutir um processo de duas etapas sobre como estar em conformidade com os 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ços de alto volume usando um pipeline de dados. Esse processo permite armazenar campos específicos da resposta da API Address Validation de maneira a obedecer aos 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

Assim, durante esta 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 informando 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 solicitar o consentimento para corrigir o endereço armazenado.

Diagrama B: ele mostra como poderia ser uma integração completa do fluxo de consentimento do usuário:

1. Quando o usuário fizer login, verifique primeiro se há sinalizações de validação em cache no seu sistema.
2. Se houver sinalizações, 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 confirmar.
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 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.

Observação: depois que esse fluxo de trabalho for concluído, o validationFlags armazenado em cache precisará ser excluído.

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, tentamos demonstrar 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ços de alto volume como uma biblioteca de código aberto no GitHub. Confira 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 sobre como usar a biblioteca em diferentes cenários.

Próximas etapas

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

Leitura adicional sugerida:

• Aplicações de validação de endereços de alto volume
• Biblioteca do Python no github
• Confira a demonstração do recurso Address Validation.

Colaboradores

O Google mantém este artigo. Ela foi escrita pelos colaboradores a seguir.
Autores principais:

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