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

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

{
  "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 Cómo controlar las direcciones actualizadas.

La propiedad verdict

La propiedad verdict resume los resultados de la validación de la dirección y debe ser la primera propiedad que se evalúe cuando se crea la lógica de verificación de direcciones. La propiedad puede devolver 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 devuelve 4 campos para esta solicitud en particular:

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

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

Consulta Verdict en la guía de referencia.

Posible próxima acción

La propiedad possibleNextAction ofrece un resumen interpretativo del resto de la respuesta de la API, con el objetivo de ayudarte a determinar si debes o no solicitarle a tu cliente que revise o edite su dirección. Consulta Cómo compilar tu lógica de validación para obtener más detalles.

Nivel de detalle de la dirección

La granularidad de la dirección hace referencia al nivel de detalle que se usa para determinar la especificidad de una dirección o un código geográfico. La especificidad de la dirección en la respuesta validationGranularity es un indicador clave para determinar si una dirección es apta para la entrega.

La propiedad verdict devuelve estos indicadores de granularidad:

  • 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 del nivel de PREMISE no suele generar un validationGranularity a un nivel de PREMISE.
  • validationGranularity: Es el nivel de detalle con el que la API de Address Validation puede validar por completo la dirección. En la mayoría de los casos, un nivel de granularidad de PREMISE o SUB_PREMISE indica una dirección de calidad que probablemente sea apta para la entrega.
  • geocodeGranularity: Describe el nivel de detalle de la geocodificación asociada a la dirección. Por ejemplo, es posible que los registros de Google indiquen la existencia de un número de departamento, pero no la ubicación precisa de ese departamento en particular dentro de un complejo de departamentos grande. En ese caso, el validationGranularity es SUB_PREMISE, pero el geocodeGranularity es isPREMISE`.
Consulta Granularity en la guía de referencia.

Integridad de la dirección

El veredicto devuelve la propiedad addressComplete como un indicador de una dirección de alta calidad, lo que significa específicamente que no tiene componentes faltantes, sin resolver o inesperados:

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

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

Consulta addressComplete en Verdict y Address en la guía de referencia.

Calidad de la dirección

Varios campos posibles indican problemas con los componentes de la dirección o ajustes en ellos, como componentes de la 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 Verdict en la guía de referencia.

Las propiedades address y addressComponent

La propiedad address proporciona el formato de la dirección procesada que se incluye en la solicitud, junto con resúmenes a nivel de los componentes de la dirección, incluidas las partes mal escritas, las partes incorrectas reemplazadas y las partes faltantes inferidas.

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 por 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 con geocódigo asociada a 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 complete para todas las direcciones que procesa la API de Address Validation, pero indica si la dirección es de tipo residencial, comercial o un apartado postal.

Consulta la 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 esté completamente completado para cada dirección validada por el servicio. Por ese motivo, no debes confiar en esta propiedad como el único medio para validar direcciones, sino que también debes verificar verdict y address.

Consulta Cómo controlar las direcciones de Estados Unidos y la referencia de UspsData.