Fragen · Adressen

Wie füge ich meinem Formular eine Adress-Autovervollständigung hinzu?

Was der Ausfüllende sieht

Er schreibt „neuer wall“ und sieht „Neuer Wall“, mit den Orten, in denen es diese Straße gibt; hat er den Ort schon ausgefüllt, beschränken sich die Vorschläge darauf. Nach der Wahl der Straße tippt er die Hausnummer, und das Formular sagt ihm, ob sie existiert: In den Großstädten entscheidet die Hausnummer über die Postleitzahl, und die Postleitzahl, die ankommt, ist die richtige für diese Nummer, nicht eine der vielen der Stadt.

Bei der Auswahl füllen sich die Felder Straße, Postleitzahl und Ort mit dem Datensatz aus dem System, demselben wie bei der Adressprüfung. Der Bestand entsteht sauber, statt hinterher bereinigt zu werden.

Wie es abgerechnet wird

Pro Sitzung, nicht pro Tastendruck. Die Vorschlagsanfragen während des Tippens sind kostenlos; ein einziger Vorgang wird gezählt, wenn der Nutzer die Adresse auswählt und die Felder sich füllen. Ändert er danach die Hausnummer und wählt in derselben Sitzung neu, wird nicht noch einmal gezählt. Jede Sitzung erlaubt bis zu dreißig Anfragen und gilt zehn Minuten. Die Preise stehen auf der Preisseite.

Wie man es einbaut

Drei Teile:

1. Ein API-Token, aus dem persönlichen Bereich.
2. Ein kleiner Proxy auf Ihrem Server, eine Seite, die die Anfrage aus dem Browser entgegennimmt, das Token hinzufügt und sie an unseren Endpunkt weiterleitet. Er ist nötig, weil das Token nie im Code stehen darf, der im Browser läuft.
3. Das Widget ra-suggerisci.js, ohne Abhängigkeiten: Sie geben ihm die Adresse des Proxys und die Selektoren der Formularfelder, und den Rest macht es selbst: die Wartezeit beim Tippen, den Kontext der schon ausgefüllten Felder und das Füllen bei der Auswahl.

Wer es lieber selbst macht, ruft direkt den Endpunkt /api/v1/suggest auf: eine vom Client erzeugte Sitzungskennung, der getippte Text, die schon bekannten Felder als Kontext; dann die Auswahlaktion mit der gewählten Straße und der Hausnummer. Alles steht in der API-Dokumentation und in der OpenAPI-Spezifikation.

Besondere Fälle

• Andere Länder: Die Vorschläge gibt es in jedem Land mit Adressregister im Dienst (die Liste); das Formular übergibt das vom Nutzer gewählte Land, und das Widget sucht dort, mit der Form der Hausnummer und der Postleitzahl dieses Landes. Der Nutzer kann alles in ein einziges Feld schreiben („Neuer Wall 10 Hamburg“): Die Antwort sagt, wie sie es gelesen hat (parsed: Straße, Hausnummer, Postleitzahl). In einem Land ohne Register sagt die Antwort es und öffnet keine Sitzung: Das Ausfüllen geht von Hand weiter, ohne Abbuchung.
• WooCommerce und PrestaShop: Da muss nichts geschrieben werden, es gibt das WooCommerce-Plugin und das PrestaShop-Modul mit der Autovervollständigung im Checkout und der Prüfung der Bestellungen.
• Straße, die nicht erscheint: Der Nutzer kann die Adresse immer vollständig schreiben; der Datensatz durchläuft die Prüfung später, aus der Datei oder über die API.
• Mehrere Formulare, mehrere Websites: Dasselbe Token bedient alle Formulare; der Proxy kann auf jeder Website stehen oder ein einziger sein.

Was mit den Feldern passiert

Die Straße wird in der korrekten Form vervollständigt, der Ort unter denen gewählt, die diese Straße haben, die Postleitzahl vom System gesetzt und der Ortsteil (Neustadt) dazu. In den Großstädten kommt mit der Hausnummer die Postleitzahl des richtigen Abschnitts.