Guia de validação de endereços de 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. Você precisa garantir que os endereços estejam corretos para casos de uso que vão 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 só processa um endereço por vez. Neste documento, vamos analisar como usar a High Volume Address Validation em diferentes cenários, desde testes de API até validações de endereço únicas e recorrentes.

Casos de uso

Agora vamos entender os casos de uso em que a High Volume Address Validation é útil.

Teste

Muitas vezes, é necessário 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

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:

  • Por exemplo, é possível programar jobs para validar endereços com detalhes capturados durante o dia, como inscrições de clientes, detalhes de pedidos e cronogramas 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, mais tarde, 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 dos clientes).
  • É possível armazenar em cache as flags de validade de 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, geralmente é recomendável 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, 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 de 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 High Volume Address Validation, o armazenamento de dados em cache 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, você vai solicitar 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 precisam ser armazenados em cache apenas 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 concorde 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. 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 o formattedAddress e outros componentes principais da resposta. No entanto, em um cenário headless, 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 headless.

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 como CONFIRMED ou UNCONFIRMED_BUT_PLAUSIBLE.

Se a resposta da API não tiver os marcadores acima, é provável que o endereço de entrada seja de baixa qualidade. Nesse caso, você pode armazenar sinalizações em cache no 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, você pode chamar a API Address Validation com o endereço atual. A API Address Validation vai retornar o endereço corrigido, que pode ser exibido usando um prompt de 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

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 para obedecer aos Termos de Serviço e implementar a validação de endereços em grande volume.

Etapa 1:

Na primeira etapa, vamos analisar como implementar um script de validação de endereços de alto volume em 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 High Volume Address Validation.

alt_text

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

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

Portanto, durante essa 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 pegar esses endereços sinalizados, apresentá-los ao usuário e receber 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:

alt_text

  1. Quando o usuário fizer login, verifique se você armazenou em cache alguma flag de validação no 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 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 houver correções ou aceitar silenciosamente se não houver.
  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ços em grande 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 High Volume Address Validation como uma biblioteca de código aberto no GitHub. Confira para começar a usar a High Volume Address Validation rapidamente. Acesse também o artigo sobre padrões de design para saber como usar a biblioteca em diferentes cenários.

Próximas etapas

Baixe o artigo Melhore a finalização da compra, o envio e as operações com endereços confiáveis e assista ao webinar Melhore a finalização da compra, o envio e as operações com a Address Validation .

Sugestões de leitura:

Colaboradores

O Google mantém este artigo. Os colaboradores a seguir escreveram o conteúdo original.
Autores principais:

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