Domande · Indirizzi

Come aggiungo l'autocomplete degli indirizzi al mio form?

Cosa vede chi compila

Scrive «via verdi» e vede «Via Giuseppe Verdi», con i comuni in cui quella via esiste; se ha già compilato la città, i suggerimenti si stringono a quella. Scelta la via, digita il civico e il form gli dice se esiste: nelle grandi città è il civico a decidere il CAP, e il CAP che arriva è quello giusto per quel numero, non quello generico del comune.

Alla selezione i campi indirizzo, CAP, località e provincia si riempiono con il record passato dal motore, lo stesso della verifica indirizzo. L'anagrafica nasce pulita invece di essere ripulita dopo.

Come si paga

A sessione, non a tasto premuto. Le richieste di suggerimento mentre si digita sono gratuite; si conta una sola operazione quando l'utente seleziona l'indirizzo e i campi si riempiono. Se poi cambia il civico e riseleziona nella stessa sessione, non si paga di nuovo. Ogni sessione ammette fino a trenta richieste e vale dieci minuti. Il listino è nella pagina dei prezzi.

Come si integra

Tre pezzi:

1. Un token API, dall'area personale.
2. Un piccolo proxy sul tuo server, una pagina che riceve la richiesta dal browser, aggiunge il token e la inoltra al nostro endpoint. Serve perché il token non deve mai stare nel codice che gira nel browser.
3. Il widget ra-suggerisci.js, senza dipendenze: gli indichi l'indirizzo del proxy e i selettori dei campi del form, e lui fa il resto: gestisce da sé l'attesa mentre si scrive, il contesto dei campi già compilati e il riempimento alla scelta.

Chi preferisce fare da sé chiama direttamente l'endpoint /api/v1/suggerisci: un identificativo di sessione generato dal client, il testo digitato, i campi già noti come contesto; poi l'azione di selezione con la via scelta e il civico. È tutto nella documentazione dell'API e nella specifica OpenAPI.

Casi particolari

• Indirizzi esteri: il catalogo dei suggerimenti è italiano. Se il form ha un campo paese e l'utente sceglie un paese estero, la risposta lo dice e non apre nessuna sessione: la compilazione continua a mano, senza addebiti.
• Via che non compare: l'utente può sempre scrivere l'indirizzo per intero; il record passerà dalla verifica in un secondo momento, dal file o dall'API.
• Più form, più siti: lo stesso token serve tutti i form; il proxy può stare su ciascun sito o essere unico.

Cosa succede ai campi

La via viene completata nella forma corretta, il comune scelto tra quelli che hanno quella via, il CAP messo dal motore. Nelle città zonate, con il civico arriva il CAP della zona.