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 propriedade 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 Veredito 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 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 detalhe capturado do endereço enviado à API Address Validation no Maps JavaScript API. 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 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 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 detalhe 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 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.

Integridade 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.

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 seguinte propriedade verdict 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.

Próxima ação possível

O campo de veredito possibleNextAction 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 de componentes do endereço, incluindo partes mal escritas, 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 no Maps JavaScript 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 em si, como o ID do lugar.

Consulte Geocode no guia de referência.

A propriedade metadata

metadata

Essa propriedade pode não ser preenchida para todos os endereços processados pela API Address Validation no API 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 ela seja totalmente preenchida para todos os endereços validados pelo serviço. Por esse motivo, não confie nessa propriedade como o único meio de validar endereços. Em vez disso, verifique também o verdict e o address.

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