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

Υπάρχει API για την κανονικοποίηση διευθύνσεων;

Τι κάνει η κλήση

Το endpoint επαλήθευσης επαφής τακτοποιεί τη διεύθυνση στην ταχυδρομική μορφή της χώρας της και το ονοματεπώνυμο που τη συνοδεύει. Διαβάζει οδό, αριθμό, ταχυδρομικό κώδικα και πόλη μαζί, όχι ένα πεδίο τη φορά, και δηλώνει κάθε διόρθωση. Η χώρα μπαίνει στο country_code (ISO 3166-1) ή στο country, γραμμένη όπως να είναι: «GR», «Ελλάδα», «Greece».

Μία επαφή τη φορά στο σώμα του αιτήματος, ή μια λίστα στο πεδίο items, έως πεντακόσιες ανά κλήση. Κάθε κλήση χρειάζεται ένα token, που δημιουργείτε από τον λογαριασμό σας μετά την εγγραφή και περνάτε στην κεφαλίδα Authorization: Bearer. Στο token μπορεί να δοθεί ημερομηνία λήξης, ή να μείνει σε ισχύ μέχρι να το ανακαλέσετε.

Πώς επιστρέφει το αποτέλεσμα

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

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

Μεμονωμένη διεύθυνση ή μαζικές εργασίες

Κάτω από τα πεντακόσια αιτήματα παίρνετε την απάντηση αμέσως, στην ίδια κλήση: η τυπική περίπτωση μιας φόρμας εγγραφής ή ενός ταμείου ηλεκτρονικού καταστήματος, όπου η διεύθυνση πρέπει να ελεγχθεί τη στιγμή που την πληκτρολογεί ο χρήστης. Για μεγαλύτερες λίστες, έως εκατό χιλιάδες διευθύνσεις τη φορά, προσθέστε "async": true: το αίτημα επιστρέφει αμέσως έναν κωδικό εργασίας και η επεξεργασία μπαίνει στην ουρά, την ίδια που εξυπηρετεί τις μαζικές εργασίες που ανεβαίνουν από τον ιστότοπο. Διαβάζετε το αποτέλεσμα με ένα GET στο ίδιο endpoint περνώντας τον κωδικό, σε JSON ή, αν χρειάζεστε αρχείο προς λήψη, σε CSV.

Αυτόματη συμπλήρωση για τις φόρμες σας

Αν φτιάχνετε μια φόρμα διεύθυνσης, το /api/v1/suggest σας δίνει αυτόματη συμπλήρωση όσο ο χρήστης πληκτρολογεί: οδός, πόλη και αριθμός προτείνονται καθώς γράφει, και το πεδίο είναι ήδη ελεγμένο κατά την επιλογή, αντί να χρειάζεται έλεγχος αργότερα με χωριστή κλήση. Ο κατάλογος προτάσεων καλύπτει σήμερα την Ιταλία· για τις άλλες χώρες η απάντηση το δηλώνει και η φόρμα συνεχίζει με χειροκίνητη καταχώριση, χωρίς χρέωση. Χρησιμοποιείται από δικό σας διακομιστή, που λειτουργεί ως proxy προς το endpoint: το token δεν πρέπει ποτέ να εμφανίζεται στον browser του τελικού χρήστη.

Πότε έχει νόημα η ενσωμάτωση

Έχει νόημα όταν η διεύθυνση μπαίνει στα αρχεία σας ξανά και ξανά, όχι μία φορά: μια φόρμα εγγραφής, το ταμείο ενός ηλεκτρονικού καταστήματος, ένα CRM που τροφοδοτείται από πολλά κανάλια. Ο έλεγχος εκεί, τη στιγμή που μπαίνει, αποτρέπει τη συσσώρευση λάθος διευθύνσεων που έπειτα πρέπει να καθαριστούν μαζικά πριν από κάθε αποστολή. Αν αντίθετα έχετε ήδη μια λίστα που πρέπει να διορθωθεί μία φορά, είναι απλούστερο να την ανεβάσετε ως αρχείο Excel ή CSV από τον ιστότοπο: ίδια μηχανή, χωρίς ούτε μία γραμμή κώδικα.

Σφάλματα, όρια και πλήρης τεκμηρίωση

Κάθε απάντηση έχει έναν κωδικό HTTP συνεπή με ό,τι συνέβη: 401 αν το token λείπει ή δεν είναι έγκυρο, 413 αν η παρτίδα υπερβαίνει το όριο, 429 αν ξεπεράσατε τον επιτρεπόμενο αριθμό αιτημάτων ανά λεπτό, 402 αν οι μονάδες δεν αρκούν για την κλήση. Μια διεύθυνση που δεν μπορεί να κανονικοποιηθεί δεν είναι σφάλμα του API: η απάντηση έρχεται ούτως ή άλλως, με το αποτέλεσμα να εξηγεί γιατί.

Στη σελίδα του API βρίσκετε όλα τα endpoint — διεύθυνση, αφαίρεση διπλοεγγραφών, email, τηλέφωνο, ιστότοπος, εμπλουτισμός ονοματεπωνύμου — με παραμέτρους, παραδείγματα curl και κωδικούς σφαλμάτων πλήρως. Αν δουλεύετε με εργαλείο που εισάγει προδιαγραφές, υπάρχει και το openapi.json.

Μια ελάχιστη κλήση

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