Preguntas · Direcciones

¿Cómo añado el autocompletado de direcciones a mi formulario?

Qué ve quien rellena el formulario

Escribe «calle alcala» y ve «Calle de Alcalá», con los municipios en los que esa calle existe; si ya ha rellenado la ciudad, las sugerencias se ciñen a ella. Elegida la calle, escribe el número y el formulario le dice si existe: en las ciudades grandes es el número el que decide el código postal, y el que llega es el correcto para ese tramo, no uno cualquiera del municipio.

Al seleccionar, los campos de dirección, código postal y localidad se rellenan con el registro pasado por el motor, el mismo de la verificación de direcciones. La base de datos nace limpia en vez de limpiarse después.

Cómo se cuenta

Por sesión, no por tecla pulsada. Las peticiones de sugerencia mientras se escribe son gratuitas; se cuenta una sola operación cuando el usuario selecciona la dirección y los campos se rellenan. Si después cambia el número y vuelve a seleccionar en la misma sesión, no se cuenta otra vez. Cada sesión admite hasta treinta peticiones y dura diez minutos. La lista de precios está en la página de precios.

Cómo se integra

Tres piezas:

1. Un token de API, desde tu área personal.
2. Un pequeño proxy en tu servidor, una página que recibe la petición del navegador, añade el token y la reenvía a nuestro endpoint. Hace falta porque el token nunca debe estar en el código que se ejecuta en el navegador.
3. El widget ra-suggerisci.js, sin dependencias: le indicas la dirección del proxy y los selectores de los campos del formulario, y él hace el resto: gestiona por sí solo la espera mientras se escribe, el contexto de los campos ya rellenados y el relleno al elegir.

Quien prefiere hacerlo por su cuenta llama directamente al endpoint /api/v1/suggest: un identificador de sesión generado por el cliente, el texto escrito, los campos ya conocidos como contexto; después la acción de selección con la calle elegida y el número. Está todo en la documentación de la API, junto con la especificación OpenAPI.

Casos particulares

• Otros países: las sugerencias existen en cada país con el registro de direcciones en servicio (la lista); el formulario pasa el país elegido por el usuario y el widget busca allí, con la forma del número y del código postal de ese país. El usuario puede escribirlo todo en un solo campo («Rua de Santa Catarina 110 Porto»): la respuesta dice cómo lo ha leído (parsed: calle, número, código postal). En un país sin registro la respuesta lo dice y no abre ninguna sesión: se sigue rellenando a mano, sin cargos.
• Lenguas cooficiales: una calle escrita en catalán, gallego o euskera se reconoce igual; el nombre se conserva como lo ha escrito el usuario, puesto en forma.
• WooCommerce y PrestaShop: no hace falta escribir nada, están el plugin para WooCommerce y el módulo para PrestaShop con el autocompletado en el checkout y la verificación de los pedidos.
• Calle que no aparece: el usuario siempre puede escribir la dirección entera; el registro pasará por la verificación más adelante, desde el archivo o desde la API.
• Varios formularios, varios sitios: el mismo token sirve para todos los formularios; el proxy puede estar en cada sitio o ser uno solo.

Qué pasa con los campos

La calle se completa en su forma correcta, el municipio se elige entre los que tienen esa calle, el código postal lo pone el motor. En las ciudades con varios distritos postales, con el número llega el código postal del tramo.