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 que variam de verificação de ID do cliente a entrega e muito mais.

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 mostrar como usar a validação de endereço de alto volume em diferentes cenários, desde testes 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.

Teste

Muitas vezes, você quer testar a API Address Validation executando milhares de endereços. Você pode ter os endereços em um arquivo de valores separados por vírgulas e querer validar a qualidade deles.

Validação única de endereços

Durante a integração com a API Address Validation, você quer validar seu banco de dados de endereços atual em relação ao banco de dados de usuários.

Validação recorrente de endereços

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

• Você pode ter jobs programados para validar endereços com base nos detalhes coletados 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 para 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 do cliente)
• É possível armazenar em cache sinalizações de validade em 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.

Teste agora:acesse o console do Google Cloud e ative a API Address Validation.

Cache para uso de produção

Observação: os elementos de resposta específicos descritos na seção a seguir podem ser armazenados por até 30 dias consecutivos. Todos esses elementos de resposta precisam ser excluídos após 30 dias.

Ao usar a API Address Validation, muitas vezes é necessário armazenar em cache parte da resposta da chamada de API. Embora nossos Termos de Serviço limitem os dados que podem ser armazenados em cache, todos os dados que podem ser armazenados em cache na 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 em relação ao 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 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 pode ser inválido. Nesse caso, solicite ao usuário um endereço corrigido na próxima interação com o app.

• 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 precisam 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 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 de compra. Há um entendimento de que você 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-chave da resposta. No entanto, em um cenário sem servidor, o 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 servidor.

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 tiver os marcadores a seguir, você pode ter certeza de que o endereço de entrada tem qualidade de 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 é definido como CONFIRMEDou UNCONFIRMED_BUT_PLAUSIBLE.

Se a resposta da API não contiver os marcadores acima, o endereço de entrada provavelmente será de baixa qualidade, e você poderá armazenar em cache as flags no seu banco de dados para refletir isso. As flags em cache indicam que o endereço como um todo tem baixa qualidade, enquanto flags mais detalhadas, como "Spell Corrected", 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 vai retornar o endereço corrigido, que você pode mostrar usando 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 sem servidor

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 do lado do servidor ou da 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 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 próxima seção, vamos discutir um processo de duas etapas sobre como se conformar 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ço de alto volume de um pipeline de dados. Esse processo permite que você armazene 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, é possível armazenar em cache os seguintes dados do addressComponent:

• confirmationLevel
• inferred
• spellCorrected
• replaced
• unexpected

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

Para mais informações, consulte os 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 usar esses endereços sinalizados e apresentá-los ao usuário para que ele conceda consentimento para corrigir o endereço armazenado.

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

1. Quando o usuário fizer login, primeiro verifique se você armazenou em cache as flags de validação no seu sistema.
2. Se houver flags, 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 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. Quando o usuário aceitar, você poderá armazenar em cache o formattedAddress no banco de dados.

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

Conclusão

A validação de endereço 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 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 para começar a desenvolver com a validação de endereço de alto volume rapidamente. Confira 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 documento técnico Melhorar a finalização da compra, o envio e as operações com endereços confiáveis e assista o webinar Como melhorar a finalização da compra, o envio e as operações com a validação de endereço .

Leitura adicional sugerida:

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

Colaboradores

Este artigo é mantido pelo Google. Os seguintes colaboradores a escreveram originalmente.
Autores principais:

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