Entender uma resposta básica de validação de endereço

A API Address Validation fornece um corpo de resposta como um arquivo que contém duas propriedades de nível superior:

• result, um objeto do tipo ValidationResult
• responseID

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

Este documento se concentra no objeto result. Para informações sobre responseID, consulte Processar endereços atualizados.

A propriedade verdict

A propriedade verdict resume os resultados da validação de endereço e deve ser a primeira propriedade a ser avaliada ao criar a lógica de verificação de endereço. A propriedade pode retornar vários campos, dependendo da qualidade do endereço de saída. Por exemplo, o exemplo a seguir mostra a propriedade verdict de um endereço de boa qualidade, que retorna quatro campos para essa solicitação específica:

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

As seções a seguir resumem todos os campos da propriedade verdict.

Granularidade do endereço

A granularidade do endereço se refere ao nível de detalhes usado para determinar a especificidade de um endereço ou geocódigo. A especificidade do endereço na resposta validationGranularity é um indicador importante para saber se um endereço pode ser entregue.

A propriedade verdict retorna estes indicadores de granularidade:

• inputGranularity: descreve o nível de detalhes capturado do endereço enviado para a API Address Validation. O nível de detalhes do endereço na solicitação influencia o nível de detalhes do endereço na resposta de validação. Por exemplo, um endereço com inputGranularity abaixo de PREMISE abaixo nível não normalmente resulta em um validationGranularity para um PREMISE nível
• validationGranularity: o nível de granularidade A API Address Validation pode ser usada para validar totalmente o endereço. Na maioria dos casos, O nível de granularidade de PREMISE ou SUB_PREMISE indica um endereço de qualidade. que é uma entrega provável.
• geocodeGranularity: descreve o nível de detalhamento do geocódigo. associadas ao endereço. Por exemplo, os registros do Google podem indicar a existência de um número de apartamento, mas não o local exato dele. apartamento específico em um grande complexo de apartamentos. Nesse caso, o validationGranularity é SUB_PREMISE, mas geocodeGranularityisPREMISE`.

Completude do endereço

O veredito retorna a propriedade addressComplete como um indicador de um endereço de alta qualidade, o que significa especificamente que ele não tem componentes ausentes, não resolvidos ou inesperados:

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

Quando o endereço tem componentes ausentes, não resolvidos ou inesperados, o campo é definido como false.

Qualidade do endereço

Vários campos possíveis indicam problemas com componentes de endereço ou ajustes, como componentes de endereço inferidos ou ausentes. Por exemplo, a propriedade verdict a seguir indica um endereço com componentes não confirmados e um campo addressComplete ausente:

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

Propriedades address e addressComponent.

A propriedade address fornece formatação para o endereço processado fornecido em a solicitação, junto com resumos em nível de componente do endereço, incluindo partes do endereço com erros ortográficos, substituição de partes incorretas e inferências ausentes partes

A propriedade addressComponent é um subcomponente de address que fornece uma lista detalhada dos elementos (ou componentes) do endereço que o A API Address Validation foi processada. A API identifica cada componente campo fornece pelo nome, tipo e nível de confirmação.

A propriedade geocode

A propriedade geocode indica o local geocodificado associado à entrada. endereço IP. Essa propriedade fornece detalhes sobre o local, como o ID de lugar.

A propriedade metadata

Essa propriedade pode não ser preenchida para todos os endereços processados pela API Address Validation, mas indica se o endereço é residencial, comercial ou uma caixa postal.

A propriedade uspsData

Esta propriedade fornece informações úteis para endereços postais nos Estados Unidos. No entanto, não há garantia de que ele será totalmente preenchido para todos os endereços validados pelo serviço. Por esse motivo, você não deve confiar nessa propriedade como a é uma forma exclusiva de validar endereços. Em vez disso, verifique os verdict e address também.