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, só é processado 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 existente 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 agendado tarefas para validar endereços para detalhes capturados durante o dia, por exemplo, de inscrições de clientes, detalhes de 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 recebe 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 flags de validade são recuperadas da API Address Validation quando um cliente individual faz login.

Armazenamento em cache para uso em produção

Ao usar a API Address Validation, geralmente é necessário armazenar em cache alguma parte da resposta da chamada de API. Nossos Termos de Serviço limitam quais dados podem ser armazenados em cache. No entanto, isso também precisa ser feito na conta de usuário. Isso significa que, no banco de dados, os metadados do endereço ou endereço precisam ser armazenados em cache no endereço de e-mail ou outro ID principal do usuário.

Para o caso de uso da Validação de endereço de alto volume, o armazenamento em cache de dados precisa seguir os Termos de serviço específicos 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ê solicitará um endereço corrigido ao usuário na próxima interação com seu 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 seu endereço e que está de acordo 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ê está ciente de que armazenará em cache e processará o endereço para fins de envio de encomendas.

Com o consentimento do usuário, você pode armazenar formattedAddress e outros componentes importantes 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 ocorre 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, terá certeza de que o endereço de entrada tem a qualidade da 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 está definido comoCONFIRMEDouUNCONFIRMED_BUT_PLAUSIBLE

Se a resposta da API não contiver os marcadores acima, o endereço de entrada provavelmente seria de má qualidade, e você pode armazenar em cache os sinalizadores em seu banco de dados para refletir isso. 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 com o cliente com um endereço sinalizado como de baixa qualidade, você pode chamar a API Address Validation com o endereço existente. A API Address Validation retornará o endereço corrigido, que você pode exibir em um prompt 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

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 atender aos 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 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.

alt_text

  • De acordo com os Termos de Serviço , é possível armazenar addressComplete, validationGranularity and validationFlags em cache ao validar endereços sem comando.

  • Você pode armazenar o addressComplete,validationGranularity and validationFlags, PlaceID em cache em relação a um UserID específico no banco de dados do cliente.

Assim, durante esta etapa da implementação, armazenaremos em cache os campos mencionados acima no UserID.

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

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 conseguir o consentimento dele para corrigir o endereço armazenado.

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

alt_text

  1. Quando o usuário fizer login, verifique primeiro se as flags de validação estão armazenadas em cache no sistema, como:

    • addressComplete é verdadeira
    • validationGranularity não é PREMISE nem SUB_PREMISE
    • validationFlags sendo inferred,spellCorrected,replaced,unexpected.
      • Se não houver flags, há alta confiança de que o endereço armazenado em cache atual é de boa qualidade e pode ser usado.

  2. Se houver sinalizações, apresente ao usuário uma interface para corrigir/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 forem feitas correções 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.

Pseudocódigo da implementação da etapa 2:

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

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 a Address Validation .

Leitura adicional sugerida:

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