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, veremos cómo usar la validación de direcciones de alto volumen en diferentes situaciones, desde pruebas de API hasta validación 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, es conveniente 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 quieras validar su calidad.

Validación única de direcciones

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

Validación recurrente de direcciones

En varias situaciones, se requiere validar las direcciones de forma recurrente:

  • Es posible que hayas programado trabajos para validar las direcciones de los detalles capturados durante el día, por ejemplo, desde los registros de los clientes, los detalles de los pedidos y los programas de entrega.
  • Es posible que recibas volcados de datos que contengan direcciones de diferentes departamentos, por ejemplo, de ventas a marketing. A menudo, el nuevo departamento que recibe las direcciones quiere validarlas antes de usarlas.
  • Puedes recopilar direcciones durante encuestas o varias promociones y, luego, actualizarlas en el sistema en línea. Quieres 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:

  • Estás llamando a la API de Address Validation con direcciones de una base de datos de clientes (es decir, una base de datos con detalles del cliente).
  • Puedes almacenar en caché 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 de producción

Cuando usas la API de Address Validation, a menudo es conveniente almacenar en caché 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é, los datos que se pueden almacenar en caché desde la API de Address Validation deben almacenarse 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 función de la dirección de correo electrónico de un usuario o de otro ID principal.

En el caso de uso de validación de direcciones de alto volumen, el almacenamiento en caché de datos debe seguir los Términos específicos del servicio de la API de Address Validation, que se describen en el artículo 11.3. En función de esta información, podrás determinar si la dirección de un usuario es no válida, en cuyo caso le pedirás que corrija la dirección durante su próxima interacción con tu aplicación.

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

Si deseas almacenar en caché información sobre la dirección real, esos datos deben almacenarse en caché solo con el consentimiento del usuario. De esta manera, se garantiza que el usuario sepa bien por qué un servicio en particular almacena su dirección y que está de acuerdo con las condiciones para 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 la 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 servidor, 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 esta situación sin cabeza.

Comprende la respuesta

Si la respuesta de la API de Address Validation contiene los siguientes marcadores, puedes confiar en que la dirección de entrada es de calidad para publicarse:

  • 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 lo siguiente:
    • Inferred(Nota: inferred=truepuede ocurrir cuando addressComplete=true)
    • spellCorrected
    • replaced
    • unexpected y
  • confirmationLevel: El nivel de confirmación en AddressComponent está configurado comoCONFIRMEDoUNCONFIRMED_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 baja calidad, mientras que las marcas más detalladas, como la corrección ortográfica, indican el tipo específico de problema de calidad de la dirección. En la próxima interacción del cliente con 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 mostrará la dirección corregida que puedes mostrar con un mensaje de la IU. Una vez que el cliente acepte la dirección con formato, puedes almacenar en caché lo siguiente de la respuesta:

  • formattedAddress
  • postalAddress
  • addressComponent componentNames o
  • UspsData standardizedAddress

Implementa una validación de direcciones sin cabeza

Según el análisis anterior, haz lo siguiente:

  • A menudo, es necesario almacenar en caché parte de la respuesta de la API de Address Validation por motivos comerciales.
  • Sin embargo, las Condiciones del Servicio de Google Maps Platform restringen qué datos 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 alto volumen.

Paso 1:

En el primer paso, veremos cómo implementar una secuencia de comandos de validación de direcciones de alto volumen desde 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 validación de direcciones de alto volumen.

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 UserID.

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, 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 verse una integración de extremo a extremo del flujo de consentimiento del usuario:

alt_text

  1. Cuando el usuario accede, 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 muestra una 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 alto volumen es un caso de uso común que es probable que encuentres en muchas aplicaciones. En este documento, se intentan demostrar algunas situaciones y un patrón de diseño para 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 validación de direcciones de gran volumen como una biblioteca de código abierto en GitHub. Consulta este artículo para comenzar a compilar con la Validación de direcciones de alto volumen rápidamente. También visita el artículo sobre patrones de diseño para usar la biblioteca en diferentes situaciones.

Próximos pasos

Descarga el documento Mejora la confirmación de compra, la entrega y las operaciones con direcciones confiables y mira el seminario en línea Cómo mejorar 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 la escribieron originalmente.
Autores principales:

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