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

A resposta da API Address Validation contém estas propriedades de nível superior:

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // 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"
}

A propriedade verdict

A propriedade verdict resume os resultados da validação de endereço e deve ser a primeira a ser avaliada ao criar uma 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 seguinte mostra a propriedade verdict de um endereço de boa qualidade, que retorna os seguintes campos para essa solicitação específica:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

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

Consulte Verificação no guia de referência.

Granularidade do endereço

A granularidade do endereço se refere ao nível de detalhe 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 detalhe capturado do endereço enviado para a validação de endereço na API Maps JavaScript. O nível de detalhe do endereço na solicitação influencia o nível de detalhe 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 que a API Address Validation no Maps JavaScript pode validar totalmente. 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 detalhe da geocodificação associada 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 preciso para esse apartamento específico em um grande complexo. Nesse caso, o validationGranularity é SUB_PREMISE, mas o geocodeGranularity é PREMISE.
Consulte Granularidade no guia de referência.

Totalidade do endereço

O veredicto 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.

Consulte addressComplete em Verificação 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 Verificação no guia de referência.

Possível próxima ação

O campo possibleNextAction veredito oferece um resumo interpretativo da resposta da API, destinado a ajudar a determinar uma possível ação subsequente a ser tomada. Esse campo é derivado de outros campos na resposta da API e não deve ser considerado uma garantia de precisão ou capacidade de entrega do endereço.

As propriedades address e addressComponent

A propriedade address fornece a formatação do endereço processado na solicitação, além de resumos no nível do componente, incluindo partes com erros de ortografia, substituídas e 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 processado pela API Address Validation no Maps JavaScript. A API identifica cada campo de componente 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 em si, como o ID de lugar.

Consulte Geocode no guia de referência.

A propriedade metadata

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

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

A propriedade uspsData

Essa propriedade fornece informações úteis para endereços postais dos Estados Unidos. No entanto, não há garantia de que ele será totalmente preenchido para todos os endereços validados pelo serviço. Por isso, não confie nessa propriedade como a única maneira de validar endereços. Em vez disso, verifique também verdict e address.

Consulte Processar endereços dos Estados Unidos e a referência para USPSData.