Preguntas · Direcciones

¿Existe una API para normalizar direcciones?

Qué hace la llamada

El endpoint de verificación de contacto pone la dirección en la forma postal de su país, y el nombre que la acompaña. Lee vía, número, código postal y ciudad juntos, no un campo cada vez, y declara cada corrección. El país va en country_code (ISO 3166-1) o en country, escrito como venga.

Un contacto cada vez en el cuerpo de la petición, o una lista en el campo items, hasta quinientos por llamada. Cada llamada necesita un token, que generas desde tu área personal una vez registrado, y pasas en la cabecera Authorization: Bearer. Al token se le puede poner una fecha de caducidad, o dejarlo válido hasta que lo revoques.

Cómo vuelve el resultado

La respuesta tiene dos formas de la misma dirección: una legible con los acentos, la otra en la forma postal para imprimir etiquetas, en mayúsculas. Te hacen falta las dos por motivos distintos: la primera para mostrar la dirección a un operador o dentro de una interfaz, la segunda para la impresión propiamente dicha.

Con ellas viene un resultado en palabras clave — correcto, modificado con el detalle de qué ha cambiado campo por campo, o por revisar cuando la dirección no se puede reconstruir con certeza, con el motivo en claro: vía no encontrada en el municipio, datos insuficientes, número no encontrado. Nada se corrige nunca en silencio: si cambiamos algo te lo decimos, y si no estamos seguros lo decimos igual de claro en vez de adivinar. Donde el registro está en servicio recibes además las coordenadas del número, el código del municipio y, en las ciudades que lo tienen, el barrio.

Dirección individual o trabajos por lotes

Por debajo de las quinientas peticiones tienes la respuesta al momento, en la misma llamada: el caso típico de un formulario de registro o de un checkout, donde la dirección hay que verificarla en el momento en que el usuario la escribe. Para listas más grandes, hasta cien mil direcciones de una vez, añade "async": true: la petición devuelve al momento un código de trabajo y el procesado entra en cola, la misma que gestiona los trabajos por lotes cargados desde el sitio. Vuelves a leer el resultado con un GET en el mismo endpoint pasando el código, en JSON o, si necesitas el archivo para descargar, en CSV.

Autocompletado para tus formularios

Si estás construyendo un formulario de dirección, /api/v1/suggest te da el autocompletado mientras el usuario escribe: vía, ciudad y número propuestos sobre la marcha, con el campo ya verificado al seleccionar en vez de tener que controlarlo después con una llamada aparte. Debe usarse desde un servidor tuyo, que hace de proxy hacia el endpoint: el token nunca debe aparecer en el navegador del usuario final.

Cuándo tiene sentido integrarla

Tiene sentido cuando la dirección entra en la base de datos una y otra vez, no una sola: un formulario de registro, un checkout de comercio electrónico, un CRM alimentado por varios canales. Verificarla ahí, en el momento en que entra, evita acumular direcciones incorrectas que luego hay que limpiar en bloque antes de cada envío. Si en cambio ya tienes una lista que arreglar una sola vez, es más sencillo cargarla como archivo Excel o CSV desde el sitio: el mismo motor, sin escribir una línea de código.

Errores, límites y documentación completa

Cada respuesta tiene un código HTTP coherente con lo ocurrido: 401 si el token falta o no es válido, 413 si el lote supera el límite, 429 si has superado el número de peticiones por minuto permitido, 402 si el crédito no basta para cubrir la llamada. Una dirección que no se consigue normalizar no es un error de la API: la respuesta llega igualmente, con el resultado que explica por qué.

En la página de la API encuentras todos los endpoints — dirección, deduplicación, email, teléfono, sitio web, enriquecimiento del nombre — con los parámetros, los ejemplos curl y los códigos de error completos. Si trabajas con una herramienta que importa especificaciones, también está openapi.json.

Una llamada mínima

La respuesta completa trae también la forma postal, el detalle de cada campo cambiado, las coordenadas del número y los datos tal como los mandaste, para comparar.