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 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 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 API Address Validation em JavaScript do Maps. 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 do nível PREMISE geralmente 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 Veredicto 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 formatação para o endereço processado na solicitação, além de resumos no nível do componente do endereço, 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 é garantido que ele seja 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.