Cómo usar la API de Validación de dirección para procesar direcciones de gran volumen

Objetivo

Como desarrollador, a menudo trabajas con conjuntos de datos que contienen direcciones de clientes que pueden no ser de buena calidad. Debes asegurarte de que las direcciones sean correctas para los casos de uso, desde la verificación del ID del cliente hasta la entrega, y mucho más.

La API de Address Validation es un producto de Google Maps Platform que puedes usar para validar una dirección. Sin embargo, solo procesa una dirección a la vez. En este documento, analizaremos cómo usar la API de High Volume Address Validation en diferentes situaciones, desde pruebas de la API hasta validaciones de direcciones únicas y recurrentes.

Casos de uso

Ahora, comprenderemos los casos de uso en los que la Validación de direcciones de alto volumen es útil.

Prueba

A menudo, querrás probar la API de Address Validation ejecutando miles de direcciones. Es posible que tengas las direcciones en un archivo de valores separados por comas y desees validar la calidad de las direcciones.

Validación única de direcciones

Durante la integración a la API de Address Validation, deseas validar tu base de datos de direcciones existente en comparación con la base de datos de usuarios.

Validación recurrente de direcciones

Hay varias situaciones en las que se deben validar las direcciones de forma recurrente:

  • Es posible que hayas programado trabajos para validar direcciones según los detalles capturados durante el día, por ejemplo, a partir de registros de clientes, detalles de pedidos y programas de entrega.
  • Es posible que recibas volcados de datos que contengan direcciones de diferentes departamentos, por ejemplo, de ventas a marketing. El departamento nuevo que recibe las direcciones a menudo quiere validarlas antes de usarlas.
  • Puedes recopilar direcciones durante las encuestas o en varias promociones y, luego, actualizarlas en el sistema en línea. Deseas validar que las direcciones sean correctas mientras las ingresas en el sistema.

Información técnica detallada

Para los fines de este documento, suponemos lo siguiente:

  • Llamas a la API de Address Validation con direcciones de una base de datos de clientes (es decir, una base de datos con detalles de los clientes).
  • Puedes almacenar en caché las marcas de validez para direcciones individuales en tu base de datos.
  • Las marcas de validez se recuperan de la API de Address Validation cuando un cliente individual accede.

Caché para uso en producción

Cuando usas la API de Address Validation, a menudo quieres almacenar en caché alguna parte de la respuesta de la llamada a la API. Si bien nuestras Condiciones del Servicio limitan los datos que se pueden almacenar en caché, todos los datos que se puedan almacenar en caché desde la API de Address Validation se deben almacenar en caché en una cuenta de usuario. Esto significa que, en la base de datos, la dirección o los metadatos de la dirección deben almacenarse en caché en relación con la dirección de correo electrónico o algún otro ID principal del usuario.

En el caso de uso de la Validación de direcciones de gran volumen, el almacenamiento en caché de datos debe cumplir con las Condiciones Específicas del Servicio de la API de Address Validation, que se describen en la Sección 11.3. Con esta información, podrás determinar si la dirección de un usuario puede ser no válida, en cuyo caso le solicitarás una dirección corregida durante su próxima interacción con tu aplicación.

  • Datos del objeto AddressComponent
    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

Si quieres almacenar en caché información sobre la dirección real, esos datos solo se deben almacenar en caché con el consentimiento del usuario. Esto garantiza que el usuario sepa por qué un servicio en particular almacena su dirección y que acepta las condiciones de compartirla.

Un ejemplo de consentimiento del usuario sería la interacción directa con un formulario de dirección de comercio electrónico en una página de confirmación de compra. Se entiende que almacenarás en caché y procesarás la dirección para enviar un paquete.

Con el consentimiento del usuario, puedes almacenar en caché formattedAddress y otros componentes clave de la respuesta. Sin embargo, en un caso sin encabezado, el usuario no puede dar su consentimiento, ya que la validación de la dirección se realiza desde el backend. Por lo tanto, puedes almacenar en caché información muy limitada en este caso sin encabezado.

Comprende la respuesta

Si la respuesta de la API de Address Validation contiene los siguientes marcadores, puedes tener la certeza de que la dirección de entrada es de calidad apta para la entrega:

  • El marcador addressComplete en el objeto Verdict es true.
  • El validationGranularity en el objeto Verdict es PREMISE o SUB_PREMISE.
  • Ninguno de los AddressComponent está marcado como:
    • Inferred(Nota:: inferred=truepuede ocurrir cuandoaddressComplete=true)
    • spellCorrected
    • replaced
    • unexpected y
  • confirmationLevel: El nivel de confirmación en el objeto AddressComponent se establece enCONFIRMEDoUNCONFIRMED_BUT_PLAUSIBLE.

Si la respuesta de la API no contiene los marcadores anteriores, es probable que la dirección de entrada sea de baja calidad, y puedes almacenar en caché las marcas en tu base de datos para reflejar eso. Las marcas almacenadas en caché indican que la dirección en su totalidad es de mala calidad, mientras que las marcas más detalladas, como Spell Corrected, indican el tipo específico de problema de calidad de la dirección. En la próxima interacción con el cliente en la que se use una dirección marcada como de baja calidad, puedes llamar a la API de Address Validation con la dirección existente. La API de Address Validation devolverá la dirección corregida que puedes mostrar con un mensaje de la IU. Una vez que el cliente acepte la dirección con el formato correcto, puedes almacenar en caché lo siguiente de la respuesta:

  • formattedAddress
  • postalAddress
  • addressComponent componentNameso
  • UspsData standardizedAddress

Implementa una validación de direcciones sin encabezado

Según el análisis anterior, se pueden extraer las siguientes conclusiones:

  • A menudo, es necesario almacenar en caché alguna parte de la respuesta de la API de Address Validation por motivos comerciales.
  • Sin embargo, las Condiciones del Servicio de Google Maps Platform restringen los datos que se pueden almacenar en caché.

En la siguiente sección, analizaremos un proceso de dos pasos para cumplir con las Condiciones del Servicio y, luego, implementar la validación de direcciones de gran volumen.

Paso 1:

En el primer paso, analizaremos cómo implementar una secuencia de comandos de validación de direcciones de gran volumen a partir de una canalización de datos existente. Este proceso te permitirá almacenar campos específicos de la respuesta de la API de Address Validation de una manera que cumpla con las Condiciones del Servicio.

Diagrama A: En el siguiente diagrama, se muestra cómo se puede mejorar una canalización de datos con una lógica de High Volume Address Validation.

alt_text

Según las Condiciones del Servicio, puedes almacenar en caché los siguientes datos de addressComponent:

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

Por lo tanto, durante este paso de la implementación, almacenaremos en caché los campos mencionados anteriormente en relación con el ID de usuario.

Para obtener más información, consulta los detalles sobre la estructura de datos real.

Paso 2:

En el paso 1, recopilamos comentarios que indicaban que algunas direcciones del conjunto de datos de entrada podrían no ser de alta calidad. En el siguiente paso, tomaremos estas direcciones marcadas, se las presentaremos al usuario y obtendremos su consentimiento para corregir la dirección almacenada.

Diagrama B: En este diagrama, se muestra cómo podría ser una integración de extremo a extremo del flujo de consentimiento del usuario:

alt_text

  1. Cuando el usuario acceda, primero verifica si almacenaste en caché alguna marca de validación en tu sistema.
  2. Si hay marcas, debes presentarle al usuario una IU para que corrija y actualice su dirección.
  3. Puedes volver a llamar a la API de Address Validation con la dirección actualizada o almacenada en caché, y presentarle la dirección corregida al usuario para que la confirme.
  4. Si la dirección es de buena calidad, la API de Address Validation devuelve un formattedAddress.
  5. Puedes presentarle esa dirección al usuario si se realizaron correcciones o aceptarla de forma silenciosa si no hay correcciones.
  6. Una vez que el usuario acepte, puedes almacenar en caché el formattedAddress en la base de datos.

Conclusión

La validación de direcciones de gran volumen es un caso de uso común que probablemente encontrarás en muchas aplicaciones. En este documento, se intenta demostrar algunas situaciones y un patrón de diseño sobre cómo implementar una solución de este tipo que cumpla con las Condiciones del Servicio de Google Maps Platform.

Además, escribimos una implementación de referencia de la API de High Volume Address Validation como una biblioteca de código abierto en GitHub. Consúltala para comenzar a compilar con High Volume Address Validation rápidamente. También puedes consultar el artículo sobre patrones de diseño para saber cómo usar la biblioteca en diferentes situaciones.

Próximos pasos

Descarga el Informe técnico sobre cómo optimizar la confirmación de compra, la entrega y las operaciones con direcciones confiables y mira el seminario web sobre cómo optimizar la confirmación de compra, la entrega y las operaciones con la Validación de direcciones .

Lecturas adicionales sugeridas:

Colaboradores

Google mantiene este artículo. Los siguientes colaboradores escribieron el texto original.
Autores principales:

Henrik Valve | Ingeniero de soluciones
Thomas Anglaret | Ingeniero de soluciones
Sarthak Ganguly | Ingeniero de soluciones