Guia de soluções da Address Validation

Diagrama de fluxo que mostra a visão geral de alto nível das etapas de teste.

Objetivo

A Address Validation é útil para vários casos de uso, e há considerações importantes além da qualidade bruta dos resultados de teste que sugerimos que você analise. Por exemplo: uma visão holística de produtos compatíveis em um fluxo do usuário, como o Place Autocomplete e o Maps, disponibilidade regional e confiança e confiabilidade corporativas.

Quando você chegar ao ponto de avaliar a API Address Validation, confira algumas diretrizes que recomendamos usar como parte dos testes.

Os objetivos desse teste serão:

  1. Confirme se a API Address Validation é adequada para seu caso de uso.
  2. Verifique como a API Address Validation atende aos requisitos das suas soluções, como:
    • Identificar endereços de boa qualidade.
    • Alertar para entradas de endereço de baixa qualidade.
    • Fazer correções nos dados de endereço, incluindo inferências, substituições e correções ortográficas.
    • Fornecer um endereço formatado para envio.
    • Alerta sobre dados de subpremissa ausentes ou incorretos (somente nos EUA).
  3. Verifique se você vai receber um benefício mensurável ao implementar a API.

Depois de realizar o teste, você poderá responder às perguntas acima e determinar se a API é adequada para sua empresa.

Preparar os dados

O teste precisa ser realizado com uma amostra dos seus dados de endereço. Não escolha os dados para o teste, mas sim amostras aleatórias que sejam representativas das regiões geográficas em que você opera. Isso significa que, se você opera nos Estados Unidos e no Reino Unido, mas 70% dos seus negócios são realizados no Reino Unido e 30% nos EUA, a amostra precisa refletir essa divisão.

Use endereços do ponto de captura. Por exemplo, se você planeja implementar a validação de endereço na finalização da compra do seu e-commerce, use os endereços inseridos pelos clientes no formulário, antes de qualquer processamento que possa ser substituído pela implementação da API Address Validation.

Prepare uma amostra de cerca de 5.000 a 10.000 registros para o teste.

Chamar a API

Pré-requisito da seção: entender como enviar uma solicitação de validação de endereço.

Depois de preparar os dados, você precisará executar cada registro de endereço na API.

Consulte a documentação da API Address Validation para saber como chamar a API. Também temos um artigo que descreve as práticas recomendadas para usar a API Address Validation para processar endereços em grande volume.

O resultado dessa etapa precisa ser a saída de dados da API para cada registro de endereço. Em seguida, você poderá analisar os resultados para determinar a adequação da API ao seu caso de uso. Você pode usar uma planilha, um banco de dados ou outra ferramenta.

Analisar os resultados

Pré-requisito da seção: entender como lidar com a resposta de validação, especialmente o conceito de corrigir, confirmar e aceitar.

Nesta seção, vamos discutir cenários de saída que você pode analisar para avaliar a adequação da solução.

Visão geral dos principais campos da API discutidos neste documento

Dados de resposta

O que é?

Como avaliar

Como isso ajuda?

verdict.inputGranularity

Descreve a granularidade de entrada do endereço.

SUB_PREMISE

PREMISSA

PREMISE_PROXIMITY

BLOQUEAR

ROUTE

OUTRO

Permite determinar se o endereço de entrada tem dados suficientes para ser válido.

verdict.validationGranularity

Descreve a validação geral de saída do endereço.

SUB_PREMISE

PREMISSA

PREMISE_PROXIMITY

BLOQUEAR

ROUTE

OUTRO

Permite determinar a qualidade geral do endereço na saída da API.

verdict.hasInferredComponents

Sinaliza se a API inferiu um componente.

Verdadeiro/Falso

A API pode adicionar componentes ausentes quando consegue inferir os dados. Por exemplo, um código de estado ausente.

verdict.hasReplacedComponents

Sinaliza se a API substituiu um componente.

Verdadeiro/Falso

A API pode substituir componentes incorretos pelos dados corretos em alguns cenários.

verdict.addressComplete

Sinaliza se o endereço está completo.

Verdadeiro/Falso

Se a API determinar que o endereço de saída tem todos os componentes necessários, o valor será verdadeiro.

address.missingComponentTypes

Sinal para avisar se o endereço não tem componentes.

Consulte os valores na tabela dois.

Destacar componentes ausentes de um endereço incompleto.

Analisar endereços válidos

Classifique os dados retornados da API para determinar o conjunto de endereços que seu sistema aceitaria como válidos. Os principais indicadores da API são:

  • verdict.validationGranularity contém PREMISE ou melhor.
  • verdict.addressComplete é true.
  • Nenhum componente inferido ou substituído.

Consulte Aceitar um endereço para mais informações.

O resultado desse exercício deve ser um subconjunto dos dados de endereço que seriam aceitos como válidos pelo seu sistema. Nesse ponto, é possível determinar:

  • A taxa de aceitação é aceitável?
  • Se você usa um fluxo de trabalho de Address Validation, a taxa de aceitação é equivalente ou melhor?

Exemplo: endereço válido

Endereço inserido

Região

76 Buckingham Palace Road, Londres SW1W 9TQ

Reino Unido

Veredito

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true
}

Revisar endereços inválidos

Essa etapa é uma oportunidade de revisar manualmente alguns dos dados de endereço que foram marcados como inválidos e verificar se, sem usar a API Address Validation, esse endereço inválido pode causar problemas downstream.

Classifique os dados retornados da API para determinar o conjunto de endereços que seu sistema marcaria como inválidos. Os principais indicadores da API são:

  • verdict.validationGranularity definido como OTHER ou ROUTE, dependendo do seu nível de risco.
  • verdict.addressComplete é false.

Consulte Corrigir um endereço para mais informações.

O resultado desse exercício precisa ser um subconjunto dos dados de endereço que seriam marcados como inválidos pelo sistema. Nesse ponto, é possível determinar se a taxa de porcentagem inválida é aceitável.

É importante observar que marcar endereços como inválidos é uma funcionalidade essencial da API Address Validation, e uma alta taxa de endereços marcados como inválidos não reflete necessariamente um desempenho ruim da API. A API informa que há algo errado com o endereço, o que pode aumentar a eficiência do seu fluxo de trabalho ao detectar erros antes que eles causem problemas.

Exemplo: endereço inválido

Endereço inserido

Região

21 45 40th street

EUA

Veredito

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "OTHER",
  "geocodeGranularity": "OTHER",
  "hasUnconfirmedComponents": true
}

Analisar componentes ausentes ou não confirmados

Nessa etapa, os componentes ausentes ou não confirmados também podem ser revisados. Isso faz parte do objeto Address no retorno. Os dois campos são missingComponentTypes e unconfirmedComponentTypes.

Use esses campos para ajudar a detectar o motivo pelo qual um endereço é marcado como inválido pela API e colete as informações corretas para que o endereço seja válido, enviando de volta ao ponto de coleta de dados os campos específicos que estão incorretos. Essa é uma maneira de a API agregar valor, fornecendo informações específicas sobre a qualidade dos seus dados.

Exemplo: componente ausente e não confirmado

Endereço informado

Região

Rua Fictícia, Nova York, NY 10011

EUA

Veredito

{
     "inputGranularity": "ROUTE",
     "validationGranularity": "OTHER",
     "geocodeGranularity": "OTHER",
     "hasUnconfirmedComponents": true
}

Componentes ausentes e não confirmados

"missingComponentTypes": [
    "street_number"
],
"unconfirmedComponentTypes": [
    "route"
]

Analisar endereços com correções

A API Address Validation pode corrigir dados de entrada, recebendo uma entrada de endereço potencialmente inválida e gerando dados de endereço válidos. Essa é uma maneira de a API agregar valor, e é importante capturar isso como parte do teste.

Os principais indicadores são:

  • inferred, replaced ou spellCorrected definido como true em qualquer um dos addressComponents.
  • verdict.hasInferredComponents ou verdict.hasReplacedComponents definido como true.

Consulte confirmar um endereço para mais informações.

O resultado desse exercício precisa ser um subconjunto dos dados de endereço que tiveram uma correção aplicada pela API.

Uma parte desses dados pode ser revisada manualmente para determinar se a API está fazendo correções nos dados que reduziriam o atrito no fluxo de trabalho downstream.

Exemplo: endereço com uma correção

Endereço inserido

Região

76 Bruckingm Palace Road, London SW1W 9TQ

Reino Unido

Rota addressComponent

{
    "componentName": {
        "text": "Buckingham Palace Road",
        "languageCode": "en"
    },
    "componentType": "route",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

[Somente nos EUA] Revisar endereço com dados de sublocal ausentes ou incorretos

A API Address Validation pode determinar se uma subinstalação está ausente ou incorreta para endereços dos EUA.

Os principais indicadores são:

  • No objeto Address:
    • unconfirmedComponentTypes contém subpremise
    • missingComponentTypes contém subpremise
  • No objeto UspsData:
    • dpvConfirmation é D (sublocal ausente)
    • dpvConfirmation é S (subpremissa não confirmada)

Consulte Processar endereços dos Estados Unidos para mais informações.

Esse teste vai mostrar se há um problema nos seus dados com subinstalações ausentes ou incorretas, como números de apartamentos. Isso pode causar problemas posteriores, especialmente em casos de uso de entrega. A API Address Validation pode agregar valor ao seu fluxo de trabalho identificando isso com antecedência, permitindo que você implemente etapas para coletar dados corrigidos.

Exemplo: subpremissa ausente

Endereço inserido

Região

111 8th Avenue, Manhattan, NY 10011

EUA

Componente ausente

"missingComponentTypes": [
    "subpremise"
]

Confirmação de DPV de dados do USPS

"dpvConfirmation": "D"

[Somente EUA] Revisar o standardizedAddress do USPS

A API Address Validation também retorna o endereço padronizado do USPS para endereços dos Estados Unidos. Isso é especialmente importante se você precisar que os endereços formatados pelo USPS sejam impressos nos rótulos para envio.

UspsAddress pode ser analisado para visualizar esses dados e determinar se ele agrega valor ao seu fluxo de trabalho.

Exemplo: endereço padronizado do USPS

"standardizedAddress": {
    "firstAddressLine": "111 8TH AVE FL 11",
    "cityStateZipAddressLine": "NEW YORK NY 10011-5201",
    "city": "NEW YORK",
    "state": "NY",
    "zipCode": "10011",
    "zipCodeExtension": "5201"
}

Conclusão

Comece a testar: comece a testar a API Address Validation hoje mesmo para garantir dados de endereço precisos, melhorar a experiência do cliente e simplificar suas operações comerciais. Depois de seguir os cenários de teste descritos acima, você terá as informações necessárias para determinar se a API Address Validation vai agregar valor ao seu fluxo de trabalho.

Sugestões de leitura:

Colaboradores

Henrik Valve | Engenheiro de DevX