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 casos de uso como la verificación de ID del cliente, la entrega y otros aspectos.

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 validación de dirección de alto volumen en diferentes situaciones, desde la prueba de API hasta la validación única y recurrente de direcciones.

Casos de uso

Veamos ahora los casos de uso en los que la validación de direcciones de alto volumen es útil.

Pruebas

Por lo general, es recomendable 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, quieres validar tu base de datos de direcciones existente comparándola con la base de datos de usuarios.

Validación recurrente de direcciones

Varias situaciones llaman a la validación de direcciones de forma recurrente:

• Es posible que hayas programado trabajos para validar las direcciones de los detalles capturados durante el día, por ejemplo, de registros de clientes, detalles de pedidos o cronogramas de entrega.
• Es posible que recibas volcados de datos con direcciones de diferentes departamentos, p.ej., de Ventas a Marketing. El departamento nuevo que recibe las direcciones suele querer validarlas antes de usarlas.
• Es posible que recopiles las direcciones durante encuestas o en diversas promociones y, luego, las actualices en el sistema en línea. Quieres comprobar que las direcciones sean correctas mientras las ingresas en el sistema.

Información técnica detallada

A los efectos 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 de clientes).
• Puedes almacenar en caché las marcas de validez en direcciones individuales de tu base de datos.
• Las marcas de validez se recuperan de la API de Address Validation cuando un cliente individual accede.

Almacenamiento en caché para uso en producción

Cuando usas la API de Address Validation, a menudo deseas 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é, cualquier dato que pueda almacenarse en caché mediante la API de Address Validation debe almacenarse en caché de 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é con la dirección de correo electrónico u otro ID principal de un usuario.

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

• Datos del objeto Verdict

  • inputGranularity
  • validationGranularity
  • geocodeGranularity
  • addressComplete
  • hasUnconfirmedComponents
  • hasInferredComponents
  • hasReplacedComponents

• Datos del objeto AddressComponent

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

Si deseas almacenar en caché cualquier información sobre la dirección real, esos datos deben almacenarse solo con el consentimiento del usuario. Esto garantiza que el usuario sepa 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 compras. Se sabe que almacenarás en caché y procesarás la dirección con el fin de enviar un paquete.

Con el consentimiento del usuario, puedes almacenar en caché formattedAddress y otros componentes clave de la respuesta. Sin embargo, en una situación sin interfaz gráfica, un usuario no puede dar su consentimiento, ya que la validación de direcciones ocurre desde el backend. Por lo tanto, puedes almacenar en caché información muy limitada en este caso sin interfaz gráfica.

Cómo comprender la respuesta

Si la respuesta de la API de Address Validation contiene los siguientes marcadores, puedes estar seguro de que la dirección de entrada es de calidad de entregable:

• El marcador addressComplete en el objeto Veredicto es true.
• El validationGranularity del objeto Veredicto es PREMISE o SUB_PREMISE.
• Ninguno de los AddressComponent está marcado de la siguiente manera:
  • Inferred(Nota: inferred=truepuede ocurrir cuando addressComplete=true)
  • spellCorrected
  • replaced
  • unexpected y
• confirmationLevel: El nivel de confirmación en AddressComponent se establece en CONFIRMEDoUNCONFIRMED_BUT_PLAUSIBLE

Si la respuesta de la API no contiene los marcadores anteriores, es probable que la dirección de entrada sea de mala calidad, y puedes almacenar marcas en caché en tu base de datos para reflejarla. Las marcas almacenadas en caché indican que toda la dirección es de mala calidad, mientras que las marcas más detalladas, como la de corrección ortográfica, indican el tipo específico de problema de calidad de la dirección. En la siguiente interacción del cliente con una dirección marcada como de mala 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 a través de una solicitud de IU. Una vez que el cliente acepte la dirección con formato, puedes almacenar en caché lo siguiente de la respuesta:

• formattedAddress
• postalAddress
• addressComponent componentNameso
• UspsData standardizedAddress

Cómo implementar una validación de direcciones sin interfaz gráfica

En función del debate anterior:

• 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 e implementar la validación de direcciones de gran volumen.

Paso 1:

En el primer paso, veremos 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 en conformidad 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.

• De acuerdo con las Condiciones del Servicio , puedes almacenar en caché addressComplete,validationGranularity and validationFlags durante la validación de direcciones sin interfaz gráfica .

• Puedes almacenar en caché el addressComplete,validationGranularity and validationFlags, PlaceID en un UserID particular en la base de datos de clientes.

Durante este paso de la implementación, almacenaremos en caché los campos antes mencionados con el UserID.

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

Paso 2:

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

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

1. Cuando el usuario acceda, primero verifica si se almacenaron en caché las marcas de validación en el sistema, por ejemplo:

   • addressComplete es verdadero
   • validationGranularity no es PREMISE ni SUB_PREMISE.
   • validationFlags es inferred,spellCorrected,replaced,unexpected.
     • Si no hay marcas, hay un alto nivel de confianza en que la dirección almacenada en caché existente es de buena calidad y se puede usar.

2. Si hay marcas, debes presentarle al usuario una IU para que corrija o 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 presentar 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 un formattedAddress.

5. Puedes presentar esa dirección al usuario si se realizaron correcciones o aceptar silenciosamente si no hay correcciones.

6. Una vez que el usuario acepte, puedes almacenar en caché el formattedAddress en la base de datos.

Pseudocódigo en el que se implementa el paso 2:

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

Conclusión

La validación de direcciones de alto volumen es un caso de uso común que probablemente encontrarás en muchas aplicaciones. En este documento, se presentan algunas situaciones y un patrón de diseño para implementar esta solución de acuerdo con las Condiciones del Servicio de Google Maps Platform.

También redactamos una implementación de referencia de la validación de direcciones de alto volumen como una biblioteca de código abierto en GitHub. Consulta esta información para comenzar a compilar rápidamente con la validación de direcciones de alto volumen. Consulta también el artículo sobre patrones de diseño para usar la biblioteca en diferentes situaciones.

Próximos pasos

Descarga el informe sobre mejora la confirmación de la compra, la entrega y las operaciones con direcciones confiables y consulta el seminario en línea sobre cómo mejorar la confirmación de la compra, la entrega y las operaciones con la validación de direcciones .

Lecturas adicionales sugeridas:

• Aplicaciones de validación de direcciones de gran volumen
• Biblioteca de Python en GitHub
• Explora la demostración de Address Validation.

Colaboradores

Google conserva 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