Ερωτήσεις · Διευθύνσεις

Πώς προσθέτω αυτόματη συμπλήρωση διευθύνσεων στη φόρμα μου;

Τι βλέπει όποιος συμπληρώνει

Στις χώρες με μητρώο σε λειτουργία — Γερμανία, Γαλλία, Ισπανία, Ιταλία, Ολλανδία και οι άλλες του καταλόγου — γράφει τα πρώτα γράμματα της οδού και βλέπει την οδό ολογράφως, με τις πόλεις στις οποίες υπάρχει· αν έχει ήδη συμπληρώσει την πόλη, οι προτάσεις περιορίζονται σε αυτήν. Αφού διαλέξει την οδό, πληκτρολογεί τον αριθμό και η φόρμα του λέει αν υπάρχει· ο ταχυδρομικός κώδικας που έρχεται είναι ο σωστός για εκείνον τον αριθμό, όχι ο γενικός του δήμου.

Με την επιλογή τα πεδία διεύθυνσης, ταχυδρομικού κώδικα και πόλης γεμίζουν με την εγγραφή που πέρασε από τη μηχανή, την ίδια της επαλήθευσης διεύθυνσης. Το αρχείο γεννιέται καθαρό αντί να καθαρίζεται εκ των υστέρων.

Για μια ελληνική διεύθυνση δεν εμφανίζονται προτάσεις όσο πληκτρολογεί: ο χρήστης γράφει τη διεύθυνση ολόκληρη, όπως σήμερα. Η εγγραφή περνά από την επαλήθευση κατά την αποθήκευση ή αργότερα, από το αρχείο ή το API, και επιστρέφει στην ελληνική ταχυδρομική μορφή — κώδικας «105 52», πόλη με κεφαλαία, συντομογραφίες ολογράφως — με το αποτέλεσμα να δηλώνει ότι η οδός δεν επαληθεύτηκε σε μητρώο.

Πώς χρεώνεται

Ανά συνεδρία, όχι ανά πλήκτρο. Τα αιτήματα πρότασης όσο ο χρήστης πληκτρολογεί είναι δωρεάν· μία μόνο επεξεργασία μετράει όταν ο χρήστης επιλέγει τη διεύθυνση και τα πεδία γεμίζουν. Αν έπειτα αλλάξει τον αριθμό και επιλέξει ξανά στην ίδια συνεδρία, δεν χρεώνεται ξανά. Κάθε συνεδρία επιτρέπει έως τριάντα αιτήματα και διαρκεί δέκα λεπτά. Σε μια χώρα χωρίς μητρώο σε λειτουργία, όπως η Ελλάδα σήμερα, δεν ανοίγει καμία συνεδρία και δεν μετράει τίποτα. Ο τιμοκατάλογος βρίσκεται στη σελίδα τιμών.

Πώς ενσωματώνεται

Τρία κομμάτια:

1. Ένα token API, από τον λογαριασμό σας.
2. Ένα μικρό proxy στον διακομιστή σας, μια σελίδα που δέχεται το αίτημα από τον browser, προσθέτει το token και το προωθεί στο endpoint μας. Χρειάζεται γιατί το token δεν πρέπει ποτέ να βρίσκεται στον κώδικα που τρέχει στον browser.
3. Το widget ra-suggerisci.js, χωρίς εξαρτήσεις: του δίνετε τη διεύθυνση του proxy και τους επιλογείς των πεδίων της φόρμας, και κάνει τα υπόλοιπα: διαχειρίζεται μόνο του την αναμονή όσο ο χρήστης γράφει, το πλαίσιο των ήδη συμπληρωμένων πεδίων και το γέμισμα κατά την επιλογή.

Όποιος προτιμά να το κάνει μόνος του καλεί απευθείας το endpoint /api/v1/suggest: ένα αναγνωριστικό συνεδρίας που παράγει ο client, το κείμενο που πληκτρολογήθηκε, τα ήδη γνωστά πεδία ως πλαίσιο· έπειτα την ενέργεια επιλογής με την οδό που διαλέχτηκε και τον αριθμό. Όλα βρίσκονται στην τεκμηρίωση του API και στην προδιαγραφή OpenAPI.

Ειδικές περιπτώσεις

• Άλλες χώρες: οι προτάσεις υπάρχουν σε κάθε χώρα με μητρώο διευθύνσεων σε λειτουργία (ο κατάλογος)· η φόρμα περνά τη χώρα που διάλεξε ο χρήστης και το widget ψάχνει εκεί, με τη μορφή του αριθμού και του ταχυδρομικού κώδικα εκείνης της χώρας. Ο χρήστης μπορεί να γράψει τα πάντα σε ένα μόνο πεδίο («Kalverstraat 92 Amsterdam»): η απάντηση λέει πώς το διάβασε (parsed: οδός, αριθμός, ταχυδρομικός κώδικας). Σε χώρα χωρίς μητρώο η απάντηση το λέει και δεν ανοίγει καμία συνεδρία: η συμπλήρωση συνεχίζει με το χέρι, χωρίς χρέωση.
• WooCommerce και PrestaShop: δεν χρειάζεται να γράψετε τίποτα, υπάρχουν το plugin για WooCommerce και το module για PrestaShop με την αυτόματη συμπλήρωση στο ταμείο και τον έλεγχο των παραγγελιών.
• Οδός που δεν εμφανίζεται: ο χρήστης μπορεί πάντα να γράψει τη διεύθυνση ολόκληρη· η εγγραφή θα περάσει από την επαλήθευση σε δεύτερο χρόνο, από το αρχείο ή το API.
• Περισσότερες φόρμες, περισσότεροι ιστότοποι: το ίδιο token εξυπηρετεί όλες τις φόρμες· το proxy μπορεί να βρίσκεται σε κάθε ιστότοπο ή να είναι ένα.

Τι συμβαίνει σε μια ελληνική διεύθυνση

Για την Ελλάδα δεν εμφανίζονται προτάσεις όσο ο χρήστης πληκτρολογεί: η διεύθυνση καταχωρίζεται όπως γράφτηκε και τακτοποιείται κατά την αποθήκευση, μέσω του API. Ταχυδρομικός κώδικας στην ελληνική μορφή, πόλη με κεφαλαία χωρίς τόνους, οδός με το αρχικό κεφαλαίο· το αποτέλεσμα λέει ότι η οδός δεν επαληθεύτηκε σε μητρώο. Στις χώρες με μητρώο σε λειτουργία, οδός, αριθμός και ταχυδρομικός κώδικας προτείνονται από το μητρώο πριν καν αποθηκευτεί η φόρμα.