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

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

{
  "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 o responseID, consulte Processar endereços atualizados.

A propriedade verdict

A propriedade verdict resume os resultados da validação de endereço e precisa 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.

Consulte Veredito no guia de referência.

Granularidade do endereço

A granularidade do endereço refere-se ao nível de detalhamento 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 ou não.

A propriedade verdict retorna estes indicadores de granularidade:

  • inputGranularity: descreve o nível de detalhes capturado do endereço enviado à API Address Validation. O nível de detalhe do endereço na solicitação influencia o nível de detalhes na resposta de validação. Por exemplo, um endereço com um inputGranularity abaixo de PREMISE abaixo do nível normalmente não resulta em um validationGranularity para um nível PREMISE.
  • validationGranularity: o nível de granularidade em que a API Address Validation pode validar totalmente o endereço. Na maioria dos casos, um nível de granularidade de PREMISE ou SUB_PREMISE indica um endereço de qualidade que provavelmente é entregue.
  • geocodeGranularity: descreve o nível de detalhamento do geocódigo associado 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 desse apartamento específico dentro de um grande complexo de apartamentos. Nesse caso, o validationGranularity é SUB_PREMISE, mas a geocodeGranularityisPREMISE`.
Consulte Granularidade no guia de referência.

Integridade do endereço

O veredito retorna a propriedade addressComplete como um indicador para 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.

Consulte addressComplete em Veredito e Endereço no guia de referência.

Qualidade do endereço

Vários campos possíveis indicam problemas com componentes de endereço ou ajustes neles, 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
}
Consulte Veredito no guia de referência.

Propriedades address e addressComponent.

A propriedade address fornece formatação para o endereço processado fornecido na solicitação, além de resumos no nível de componente do endereço, incluindo partes do endereço com erros ortográficos, partes incorretas substituídas e partes ausentes inferidas.

Consulte Address no guia de referência.

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

Consulte addressComponent no guia de referência.

A propriedade geocode

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

Consulte Geocode no guia de referência.

A propriedade metadata

Talvez essa propriedade não seja preenchida para todos os endereços processados pela API Address Validation, mas indica se o endereço é do tipo residencial, comercial ou caixa postal.

Consulte a cobertura da API Address Validation e a referência de Address metadata.

A propriedade uspsData

Esta propriedade fornece informações úteis para endereços postais nos Estados Unidos. No entanto, não é garantido que esteja totalmente preenchido para todos os endereços validados pelo serviço. Por esse motivo, não confie nessa propriedade porque a única forma de validar endereços. Em vez disso, verifique o verdict e o address.

Consulte Tratar endereços nos Estados Unidos e a referência de UspsData.
Anterior
Enviar uma solicitação de validação de endereço
Próxima
Criar sua lógica de validação