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

Observação: este documento descreve os elementos básicos de uma resposta de Address Validation para um endereço de alta qualidade. Para orientações sobre como trabalhar com cenários de endereços reais e criar lógica em torno de respostas mais complexas, consulte Criar sua lógica de validaçã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

Importante: use a propriedade verdict para receber um resumo básico da qualidade do endereço.

A propriedade verdict resume os resultados da validação de endereço e deve 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, veja 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 Verdict 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 é entregável ou não.

A propriedade verdict retorna estes indicadores de granularidade:

• inputGranularity: descreve o nível de detalhe capturado do endereço enviado à Address Validation na API Maps JavaScript. 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 do nível PREMISE geralmente não resulta em um validationGranularity para um nível PREMISE.
• validationGranularity: o nível de granularidade que a Address Validation na API Maps JavaScript pode usar para 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 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 de apartamentos. Nesse caso, o validationGranularity é SUB_PREMISE, mas o geocodeGranularity é PREMISE.

Consulte Granularidade no guia de referência.

Endereço completo

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.

Observação: quando a propriedade addressComplete não aparece no veredito após a inspeção manual, o valor dela é falso. Nesse caso, consulte o veredito para verificar a presença da propriedade addressComplete ou consulte a propriedade diretamente. Consulte Qualidade do endereço abaixo para ver um exemplo.

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 Verdict no guia de referência.

Próxima ação possível

Este produto ou recurso está em pré-lançamento (pré-GA). Os produtos e recursos em pré-GA têm suporte limitado, e é possível que as mudanças neles não sejam compatíveis com versões anteriores. Os produtos e recursos em pré-GA são cobertos pelos Termos de Serviço da Plataforma Google Maps. Para mais detalhes, consulte as descrições da fase de lançamento.

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

As propriedades address e addressComponent

Importante: use a propriedade address para obter a formatação do endereço. Use o subcomponente addressComponent para investigar erros e fornecer informações sobre eles aos clientes. No entanto, não crie sua integração para depender do nível de confirmação específico para componentes de endereço. Consulte Criar sua lógica de validação para orientações de integração.

A propriedade address fornece formatação para o endereço processado fornecido na solicitação, além de resumos do endereço no nível do componente, incluindo partes do endereço com erros de ortografia, 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 em API 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

Importante: use a propriedade geocode para receber o ID de lugar ou de geocodificação quando sua lógica tiver chamado a API Geocoding anteriormente.

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

Consulte Geocode no guia de referência.

A propriedade metadata

Importante: use a propriedade metadata para determinar o tipo de propriedade associada ao endereço: residencial, caixa postal ou comercial.

Essa propriedade pode não ser preenchida para todos os endereços processados pela Address Validation na 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 de Address metadata.

A propriedade uspsData

Importante: use a propriedade uspsData para conferir os níveis de confiança de entrega e outros detalhes do USPS sobre endereços dos EUA.

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 use essa propriedade como o único meio de validar endereços. Verifique também verdict e address.

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