Comprender una respuesta de validación de dirección básica

La API de Address Validation toma una dirección como entrada. Luego, la API muestra una respuesta que contiene lo siguiente:

  • El veredicto de la validación de toda la dirección y de cada componente de la dirección (número de calle, nombre de la calle, ciudad, etc.).

  • Una sola string que contiene la dirección completa según lo determinado por la API.

  • Propiedades individuales que contienen cada componente de la dirección, según lo determinado por la API

  • Una lista de los componentes de dirección faltantes, de los componentes de dirección sin confirmar y de los componentes de la dirección que no se pudieron resolver.

  • Es el geocódigo de la dirección.

  • Para las regiones “US” y “PR”, los datos de USPS para la dirección

Con la respuesta de la API, puedes asegurarte de que la dirección exista y sea de la calidad necesaria para tus necesidades. Si la respuesta de la API indica que una dirección está incompleta o es incorrecta, puedes pedirle al usuario que la actualice. Después de que el usuario complete la actualización, usa la API para validar la dirección actualizada.

En este documento, se describe cómo procesar la respuesta de la API y cómo manejar algunos errores comunes en la dirección de entrada que detecta la API.

Nota: Para tener una mejor idea de cómo la API maneja los errores con la dirección de entrada, prueba la demostración. La demostración te permite ingresar direcciones y, luego, ver la respuesta como contenido visualizado y como un objeto JSON.

Acerca de la respuesta

El objeto JSON que representa la respuesta de validación contiene dos propiedades de nivel superior: result, del tipo ValidationResult y 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"
}

En este documento, se describe cómo interpretar la propiedad result. Para obtener más información sobre responseID, consulta Cómo validar una dirección actualizada y Cómo proporcionar comentarios de validación de direcciones.

Comprende la propiedad de veredicto

La propiedad verdict en la respuesta de validación indica los resultados generales de la validación. La propiedad verdict contiene las siguientes propiedades:

  • inputGranularity

    Indica el nivel de detalle de la dirección de entrada según lo determinado mediante el análisis de la dirección, pero sin su validación. Por ejemplo, estas propiedades pueden contener PREMISE para una dirección que se resuelve como el resultado a nivel de edificio, BLOCK para una dirección que se convierte en un bloque o ROUTE para una dirección detallada en una ruta, como una calle, una ruta o una autopista.

  • validationGranularity

    Indica el nivel de detalle con el que la API puede validar la dirección. Ten en cuenta que este es el nivel de detalle de la dirección validada y no el de la dirección que se muestra en address.formattedAddress o address.postalAddress.

  • geocodeGranularity

    Indica el nivel de detalle de la ubicación geográfica generada.

  • addressComplete

    Es verdadero si la API considera que la dirección está completa. Esto significa que no hay tokens sin resolver (strings o símbolos de dirección), componentes de dirección inesperados o componentes de dirección faltantes en la propiedad address.

  • hasUnconfirmedComponents, hasInferredComponents y hasReplacedComponents

    Propiedades que indican si al menos un componente de la dirección no se puede categorizar o validar, si se infirió (agregado) al menos un componente de la dirección que no estaba en la entrada y si se reemplazó al menos un componente de la dirección.

Veredicto de una dirección completa con componentes inferidos

En el siguiente ejemplo, se muestra la propiedad verdict de una dirección completa con componentes inferidos:

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

Ten en cuenta que el nivel de detalle se resuelve en un entorno local y que la dirección está completa, pero la API infirió el valor de algunos componentes. En este ejemplo, la dirección de entrada omitió el código postal de EE.UU. que la API pudo inferir del resto de la dirección. Consulta Componentes de dirección inferida para obtener un ejemplo más completo.

Veredicto para una dirección con componentes no confirmados

Si bien una dirección de entrada se puede considerar completa incluso si hay componentes inferidos, una dirección no se puede considerar completa si hay tokens de dirección sin resolver, componentes de dirección inesperados o componentes de dirección faltantes.

En el siguiente ejemplo, hasUnconfirmedComponents se configura como true para indicar que la dirección tiene al menos un componente de dirección que no se puede categorizar ni validar:

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

En este caso, el nivel de detalle de la dirección validada y geocodificada se establece en OTHER, y la propiedad addressComplete se omite de la respuesta para indicar que la dirección no está completa. Consulta Componentes de dirección faltantes y no confirmados para obtener un ejemplo más completo.

Respuestas de ejemplo

En las siguientes secciones, se muestran respuestas para situaciones diferentes, incluidas las de una dirección completa y errores comunes de validación de direcciones. En estos ejemplos, se dan las siguientes situaciones:

  • Si la respuesta contiene addressComplete establecido en true, la API determinó que la dirección de entrada era de buena calidad.

  • Si la API de Address Validation indica que realizó cambios significativos en la dirección o que hay errores en la dirección, debes confirmar la dirección devuelta con tu cliente.

Dirección completa de buena calidad

Cuando la API determina que una dirección está completa, configura addressComplete como true en la propiedad verdict de la respuesta.

Por ejemplo:

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

La propiedad address de la respuesta contiene todos los detalles de la dirección que determina la API. La respuesta incluye la propiedad formattedAddress, que contiene la dirección corregida y validada como una string de una sola línea. Te recomendamos que uses la dirección de una sola línea que se incluye en el campo formattedAddress para la dirección completa, ya que puede contener correcciones y adiciones menores, como mayúsculas y ZIP+4 en EE.UU.

La propiedad address también indica si hay algún problema, según lo determinado por la API, para cada componente de dirección. Para cada componente, como el nombre de la calle o la ciudad, el campo address contiene un campo confirmationLevel. Estos son algunos de los valores posibles:

  • CONFIRMED indica que la API pudo verificar que el componente existe.
  • UNCONFIRMED_BUT_PLAUSIBLE indica que no se pudo confirmar el componente, pero es razonable.
  • UNCONFIRMED_AND_SUSPICIOUS indica que no se confirmó el componente y es probable que sea incorrecto.

Por ejemplo:

"address": {
  // Validated address as a single string.
  "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
  // Individual validated address components.
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043-1351",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  // Validation results for each component.
  "addressComponents": [
    {
      "componentName": {
        "text": "1600",
        "languageCode": "en"
      },
      "componentType": "street_number",
      "confirmationLevel": "CONFIRMED"
    },
    {
      "componentName": {
        "text": "Amphitheatre Pkwy",
        "languageCode": "en"
      },
      "componentType": "route",
      "confirmationLevel": "CONFIRMED"
    },
    …
  ]
  // List of any missing, unconfirmed, or unresolved address components.
  // These properties are omitted from the response if they are empty.
  "missingComponentTypes": [],
  "unconfirmedComponentTypes": [],
  "unresolvedTokens": []
}

Componentes de dirección inferida

Si la dirección de entrada no contiene una dirección completa, la API intenta agregar los componentes de dirección faltantes a la respuesta. Estos componentes agregados se denominan componentes de dirección inferidos.

Por ejemplo, debes usar la siguiente dirección de entrada:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1600 Amphitheatre Pkwy"]
  }
}

Ten en cuenta que esta dirección no contiene un código postal de EE.UU. La API puede determinar el código postal del resto de la dirección de entrada y agregarlo a la respuesta.

En este ejemplo, la propiedad verdict establece hasInferredComponents en true para indicar que la API infirió el valor de uno o más componentes. Sin embargo, dado que esta fue una corrección menor, la API establece addressComplete en true para indicar que la dirección de entrada seguía siendo de buena calidad.

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

Para el componente que se infirió, la API configura inferred como true en el elemento correspondiente del array addressComponents de la propiedad address:

{
  "componentName": {
    "text": "94043"
  },
  "componentType": "postal_code",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

Errores ortográficos en la dirección ingresada

Es común que haya errores de ortografía en una dirección de entrada, como un error tipográfico en la ciudad o el estado. Por ejemplo, en lugar de “Mountain View”, ingresas “MontainView” como la parte de la localidad de una dirección:

{
  "address": {
    "regionCode" : "US",
    "locality" : "MontainView",
    "addressLines" : ["1600 Amphitheatre Pkwy"]
  }
}

En este ejemplo, la propiedad verdict indica que infirió el valor de uno o más componentes y también configura addressComplete en true para indicar que la dirección de entrada era de buena calidad porque aún pudo resolverla:

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

La API intenta corregir la dirección correctamente. El elemento de dirección correspondiente en el array addressComponents de la propiedad address muestra la string corregida en la propiedad text y también indica que hubo un error de ortografía cuando se estableció spellCorrected en true:

{
    "componentName": {
        "text": "Mountain View",
        "languageCode": "en"
    },
    "componentType": "locality",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

Componentes de dirección faltantes y no confirmados

Los usuarios pueden omitir una parte de una dirección de entrada. En el siguiente ejemplo, el usuario ingresa el número de la calle, pero no el nombre:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600"]
  }
}

En este caso, el veredicto omite la propiedad addressComplete porque falta mucha información para que la API pueda resolver la dirección. La API también configura hasUnconfirmedComponents como true para indicar que la dirección tiene componentes sin confirmar:

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

Ten en cuenta también que validationGranularity y geocodeGranularity se configuraron como OTHER porque la API no pudo resolver la dirección.

En el array addressComponents de la propiedad address, la API marca el componente del número de calle como UNCONFIRMED_BUT_PLAUSIBLE:

{
  "componentName": {
    "text": "1600",
    "languageCode": "en"
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE"
}

Por último, la API propaga los arrays missingComponentTypes y unconfirmedComponentTypes de la propiedad address con los componentes que faltan en la entrada y aquellos que no pudo confirmar:

"missingComponentTypes": [
  "route",
  "postal_code"
],
"unconfirmedComponentTypes": [
  "street_number"
]

Comprende los diferentes valores de nivel de detalle

Los valores de nivel de detalle en la respuesta proporcionan información sobre qué tan generales o precisos la API puede interpretar una dirección. Por ejemplo, debes usar la siguiente dirección de entrada:

{
  "address": {
    "regionCode": "US",
    "locality": "Northampton",
    "addressLines": ["6 South Main Street APT 456"]
  }
}

En este ejemplo, la API encuentra el número de calle en la base de datos de USPS, pero no puede encontrar el número de departamento. Además, la API no puede encontrar un geocódigo preciso para el número de calle, "6", pero puede encontrar uno para "4" y "8". En este caso, la API muestra el siguiente verdict:

"verdict": {
    "inputGranularity": "SUB_PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE_PROXIMITY",
    "addressComplete": true,
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

En esta respuesta:

  • inputGranularity es SUB_PREMISE porque la API puede analizar la dirección de entrada para el nivel de departamento. inputGranularity solo se aplica a la capacidad de las APIs para analizar la dirección de entrada. No se aplica a la validación realizada en la dirección.

  • validationGranularity es PREMISE porque la API puede validar la existencia del número de calle “6”, pero no del “APT 456”. Aunque la API no puede validar "APT 456", todavía se incluye en los campos formattedAddress y postalAddress de salida.

  • geocodeGranularity es PREMISE_PROXIMITY porque la API solo puede interpolar la ubicación geográfica; no pudo encontrar un geocódigo para la dirección exacta de entrada.

Dirección creada artificialmente detectada por USPS

Cuando el USPS identifica una dirección creada de forma artificial, el campo errorMessage de la propiedad uspsData de la respuesta contiene un mensaje de error que describe el problema. Por ejemplo:

"uspsData": {
    "errorMessage": "AMS API processing was terminated due to the detection of
    what is determined to be an artificially created address. No address beyond
    this point has been validated and/or processed. If you believe this address
    was identified in error, please contact your Vendor."
}

El envío de direcciones creadas artificialmente a la API puede llevar a la pérdida de acceso a la base de datos del USPS. Cuando recibas este mensaje de error, te recomendamos que investigues la fuente de la dirección para evitar que se envíen más direcciones artificiales a la API.

Esta medida de seguridad está diseñada para evitar la creación artificial de una lista de direcciones mediante la detección de cuándo una dirección enviada parece haberse construido de forma artificial y no se obtuvo de forma legítima. Esto debería ser un caso muy inusual.