Comprende la respuesta básica de validación de la dirección

La API de Address Validation proporciona un cuerpo de la respuesta como un objeto JSON que contiene dos propiedades de nivel superior:

• result, un objeto de tipo ValidationResult
• responseID

{
  "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 centra en el objeto result. Para obtener información sobre responseID, consulta Administra direcciones actualizadas.

La propiedad verdict

La propiedad verdict resume los resultados de la validación de la dirección y debe ser la primera que se evalúe cuando se compile la lógica de verificación de direcciones. La propiedad puede mostrar una variedad de campos, según la calidad de la dirección de salida. Por ejemplo, a continuación se muestra la propiedad verdict de una dirección de buena calidad, que muestra 4 campos para esta solicitud en particular:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true
}

En las siguientes secciones, se resumen todos los campos de la propiedad verdict.

Consulta Veredicto en la guía de referencia.

Nivel de detalle de la dirección

El nivel de detalle de la dirección se refiere al nivel de detalle que se usa para determinar la especificidad de una dirección o un geocódigo. La especificidad de la dirección en la respuesta validationGranularity es un indicador clave para determinar si una dirección es entregable o no.

La propiedad verdict muestra estos indicadores de nivel de detalle:

• inputGranularity: Describe el nivel de detalle capturado de la dirección enviada a la API de Address Validation. El nivel de detalle de la dirección en la solicitud influye en el nivel de detalle de la dirección en la respuesta de validación. Por ejemplo, una dirección con un inputGranularity por debajo de PREMISE por debajo del nivel, por lo general, no da como resultado un nivel de validationGranularity a PREMISE.
• validationGranularity: Es el nivel de detalle al que la API de Address Validation puede validar por completo la dirección. En la mayoría de los casos, un nivel de detalle de PREMISE o SUB_PREMISE indica una dirección de calidad que es probable que se pueda entregar.
• geocodeGranularity: Describe el nivel de detalle del geocódigo asociado con la dirección. Por ejemplo, los registros de Google pueden indicar que existe un número de departamento, pero no una ubicación precisa para ese departamento en particular dentro de un gran complejo de departamentos. En ese caso, validationGranularity es SUB_PREMISE, pero geocodeGranularityisPREMISE`.

Consulta Nivel de detalle en la guía de referencia.

Integridad de la dirección

El veredicto muestra la propiedad addressComplete como un indicador para una dirección de alta calidad, lo que significa que, en particular, no tiene componentes faltantes, sin resolver o inesperados:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true
}

Cuando la dirección tiene componentes inesperados, sin resolver o faltantes, el campo se establece en false.

Consulta addressComplete en Veredicto y Dirección en la guía de referencia.

Calidad de la dirección

Varios campos posibles indican problemas con los componentes de dirección o ajustes a ellos, como componentes de dirección inferidos o faltantes. Por ejemplo, la siguiente propiedad verdict indica una dirección con componentes no confirmados y un campo addressComplete faltante:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

Consulta Veredicto en la guía de referencia.

Las propiedades address y addressComponent

La propiedad address proporciona formato para la dirección procesada que se proporciona en la solicitud, junto con resúmenes de la dirección a nivel de los componentes, incluidas las partes con errores ortográficos de la dirección, el reemplazo de partes incorrectas y las partes inferidas que faltan.

Consulta Address en la guía de referencia.

La propiedad addressComponent es un subcomponente de address que proporciona una lista detallada de los elementos (o componentes) de la dirección que procesó la API de Address Validation. La API identifica cada campo de componente que proporciona su nombre, tipo y nivel de confirmación.

Consulta addressComponent en la guía de referencia.

La propiedad geocode

La propiedad geocode indica la ubicación geocodificada asociada con la dirección de entrada. Esta propiedad proporciona detalles sobre la ubicación en sí, como su ID de lugar.

Consulta Geocode en la guía de referencia.

La propiedad metadata

Es posible que esta propiedad no se propague en todas las direcciones procesadas por la API de Address Validation, pero indica si la dirección es de tipo residencial, comercial o apartado postal.

Consulta Cobertura de la API de Address Validation y la referencia de Address metadata.

La propiedad uspsData

Esta propiedad proporciona información útil para las direcciones postales de Estados Unidos. Sin embargo, no se garantiza que se propaguen por completo en cada dirección que valida el servicio. Por ese motivo, no debes confiar en esta propiedad como el único medio para validar direcciones, sino verificar también verdict y address.

Consulta Administra direcciones de Estados Unidos y la referencia de UspsData.