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 uma variedade de 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 na propriedade verdict.

Consulte Veredito no guia de referência.

Granularidade do endereço

A granularidade de 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 sinal 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 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 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 pode ser entregue.
  • geocodeGranularity: descreve o nível de detalhes 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 um local exato para esse apartamento específico em um grande complexo de apartamentos. Nesse caso, o validationGranularity é SUB_PREMISE, mas o geocodeGranularityisPREMISE`.
Consulte Granularidade no guia de referência.

Integridade do endereço

O veredito retorna a propriedade addressComplete como um sinal para um endereço de alta qualidade, o que significa especificamente que não há 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, 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.

As 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 do componente do endereço, incluindo partes escritas incorretamente, substituídas pelas partes incorretas 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 por nome, tipo e nível de confirmação.

Consulte addressComponent no guia de referência.

A propriedade geocode

A propriedade geocode indica a localização geocodificada associada ao endereço de entrada. Essa propriedade fornece detalhes sobre o próprio local, como o ID.

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 é residencial, comercial ou de caixa postal.

Consulte Cobertura da API Address Validation e a referência para Address metadata.

A propriedade uspsData

Essa propriedade fornece informações úteis sobre endereços postais nos Estados Unidos. No entanto, não é garantido que ele seja totalmente preenchido para cada endereço validado pelo serviço. Por esse motivo, não confie nessa propriedade como a única forma de validar endereços. Em vez disso, verifique verdict e address.

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