Fragen · Adressen

Gibt es eine API zur Adressnormalisierung?

Was der Aufruf tut

Der Endpunkt der Kontaktprüfung bringt die Adresse in die Postform ihres Landes und den Namen dazu. Er liest Straße, Hausnummer, Postleitzahl und Ort zusammen, nicht ein Feld nach dem anderen, und erklärt jede Korrektur. Das Land kommt in country_code (ISO 3166-1) oder in country, geschrieben wie es kommt.

Ein Kontakt je Anfrage im Body, oder eine Liste im Feld items, bis zu fünfhundert pro Aufruf. Jeder Aufruf braucht einen Token, den Sie nach der Registrierung in Ihrem Kundenbereich erzeugen und im Header Authorization: Bearer mitgeben. Der Token kann ein Ablaufdatum bekommen oder gültig bleiben, bis Sie ihn widerrufen.

Wie das Ergebnis zurückkommt

Die Antwort enthält zwei Formen derselben Adresse: eine lesbare mit Umlauten und die Postform für den Etikettendruck, in Großbuchstaben. Sie brauchen beide aus verschiedenen Gründen: die erste, um die Adresse einem Bearbeiter oder in einer Oberfläche zu zeigen, die zweite für den eigentlichen Druck.

Dazu ein Ergebnis in Schlüsselwörtern — korrekt, geändert mit dem Detail, was sich Feld für Feld geändert hat, oder zu prüfen, wenn sich die Adresse nicht sicher rekonstruieren lässt, mit dem Grund im Klartext: Straße in der Gemeinde nicht gefunden, unzureichende Daten, Hausnummer nicht gefunden. Nichts wird je stillschweigend korrigiert: ändern wir etwas, sagen wir es, und sind wir unsicher, sagen wir das ebenso klar, statt zu raten. Wo das Register im Dienst ist, bekommen Sie zudem die Koordinaten der Hausnummer, den Gemeindecode des Registers und, in Städten, die ihn haben, den Stadtteil.

Einzelne Adresse oder Stapelauftrag

Unter fünfhundert Anfragen haben Sie die Antwort sofort, im selben Aufruf: der typische Fall eines Registrierungsformulars oder eines Checkouts, wo die Adresse in dem Moment zu prüfen ist, in dem der Nutzer sie eingibt. Für größere Listen, bis zu hunderttausend Adressen auf einmal, fügen Sie "async": true hinzu: die Anfrage gibt sofort einen Auftragscode zurück und die Verarbeitung geht in die Warteschlange, dieselbe, die die von der Website hochgeladenen Stapelaufträge bearbeitet. Das Ergebnis lesen Sie mit einem GET auf denselben Endpunkt mit dem Code, als JSON oder, wenn Sie eine Datei zum Herunterladen brauchen, als CSV.

Autovervollständigung für Ihre Formulare

Wenn Sie ein Adressformular bauen, liefert /api/v1/suggest die Autovervollständigung während der Eingabe: Straße, Ort und Hausnummer werden nach und nach vorgeschlagen, das Feld ist bei der Auswahl schon geprüft, statt es später mit einem eigenen Aufruf kontrollieren zu müssen. Zu verwenden von einem Server von Ihnen aus, der als Proxy zum Endpunkt dient: der Token darf nie im Browser des Endnutzers erscheinen.

Wann die Integration Sinn hat

Sie hat Sinn, wenn die Adresse immer wieder in den Bestand kommt, nicht einmalig: ein Registrierungsformular, ein E-Commerce-Checkout, ein CRM, das aus mehreren Kanälen gespeist wird. Sie dort zu prüfen, in dem Moment, in dem sie eintrifft, vermeidet, dass sich falsche Adressen ansammeln, die dann vor jedem Versand im Stapel zu bereinigen sind. Haben Sie dagegen bereits eine Liste, die einmal in Ordnung zu bringen ist, ist es einfacher, sie als Excel- oder CSV-Datei über die Website hochzuladen: dasselbe System, ohne eine Zeile Code.

Fehler, Grenzen und vollständige Dokumentation

Jede Antwort hat einen HTTP-Code, der zu dem passt, was geschehen ist: 401, wenn der Token fehlt oder ungültig ist, 413, wenn der Stapel die Grenze überschreitet, 429, wenn Sie die erlaubte Zahl von Anfragen pro Minute überschritten haben, 402, wenn das Guthaben für den Aufruf nicht reicht. Eine Adresse, die sich nicht normalisieren lässt, ist kein API-Fehler: die Antwort kommt trotzdem, mit dem Ergebnis, das erklärt, warum.

Auf der API-Seite finden Sie alle Endpunkte — Adresse, Dublettenbereinigung, E-Mail, Telefon, Website, Namensanreicherung — mit Parametern, curl-Beispielen und den Fehlercodes im Ganzen. Wenn Sie mit einem Werkzeug arbeiten, das Spezifikationen importiert, gibt es auch openapi.json.

Ein minimaler Aufruf

Die vollständige Antwort enthält auch die Postform, das Detail jedes geänderten Feldes, die Koordinaten der Hausnummer und die Daten, wie Sie sie geschickt haben, zum Vergleich.