Address API - Integrationsleitfaden

So verbinden Sie die DQE-Vorschlags- und Validierungsendpunkte für eine optimale Adressqualität mit minimal unnötigen API-Aufrufen.

Integrationsmuster

DQE empfiehlt einen zweistufigen Ansatz:

• Stufe 1 - Adressvorschlag - wählen Sie einzeilig oder schrittweise, je nach Design Ihres Formulars
• Stufe 2 - RNVP-Validierung als Sicherheitsnetz - nur auslösen, wenn der Benutzer Freitext eingegeben oder einen DQE-Vorschlag geändert hat

Integrationsablauf

Feld „Label" - nur zur Anzeige

Das Feld Label ist ausschließlich für das Vorschlags-Dropdown formatiert. Sein Format variiert je nach Land und kann Trennzeichen, Klammern oder in eckige Klammern eingeschlossene Zahlen enthalten. Verwenden Sie es nicht, um Adressfelder zu befüllen - verwenden Sie stets die zusammen damit zurückgegebenen strukturierten Felder.

Hausnummern in eckigen Klammern (z. B. [30] RUE DE LA PAIX) zeigen an, dass die Nummer nicht in der DQE-Referenzdatenbank gefunden wurde. DQE gibt dennoch den Rest der Adresse korrekt formatiert zurück, sodass Benutzer fortfahren können. Erwägen Sie, in Klammern gesetzte Nummern in gedämpftem Stil anzuzeigen, um zu signalisieren, dass die Nummer möglicherweise überprüft werden muss - sie könnte in einem zukünftigen Datenbank-Update erscheinen.

Position der Hausnummer

Die API gibt Numero und Voie als separate strukturierte Felder zurück (RESTful: StreetNumber und Street). Verketten Sie diese in der vom Zielland festgelegten Reihenfolge.

Hinweis: Ist Numero leer, zeigen Sie nur Voie an - ohne Trennzeichen.

Straße ohne Hausnummer ausgewählt

Wenn ein Benutzer eine Straße auswählt, ohne eine Hausnummer einzugeben, gibt die API die Straßenübereinstimmung zurück und signalisiert, dass für diese Straße Nummern existieren. Erkennen Sie diesen Fall und präsentieren Sie die verfügbaren Nummern aus der bereits erhaltenen Antwort - es ist kein zusätzlicher API-Aufruf erforderlich. Dies gilt für alle Autovervollständigungsmodi: Standard-API SINGLEV2 und ADR, RESTful SINGLE und FunnelAddress.

Erkennungsbedingung

Ergänzungsfeld

Ordnen Sie Ihr Ergänzungs-Formularfeld Complement (Classic: SINGLEV2 / ADR) oder AdditionalAddress (RESTful: single / funneladdress) zu.

Nachdem der Benutzer eine Adresse ausgewählt hat, rufen Sie den dedizierten Ergänzungsschritt auf - COMPLV2 / COMPL (Classic) oder compl / funnelcompl (RESTful) - und präsentieren Sie dem Benutzer die zurückgegebenen Optionen.

Sprache der zurückgegebenen Ergebnisse

Für die meisten Länder liegen Adressdaten in nur einer Sprache vor, und die Sprache der zurückgegebenen Ergebnisse hängt vollständig von der Referenzdatenbank ab - Sie können sie nicht ändern.

Für einige Länder enthält die Datenbank Einträge in mehreren Sprachen oder Schriften. In diesem Fall wirkt der Parameter Langue als strenger Sprachfilter: Es werden nur Ergebnisse zurückgegeben, die mit der angeforderten Sprache markiert sind. Ohne diesen Parameter können alle Sprachversionen gleichzeitig zurückgegeben werden.

Länder, in denen Langue nach Sprache filtert

Adresskorrektur (RNVP)

Wenn ein RNVP-Aufruf ausgelöst wird, zeigen Sie dem Benutzer die Korrektur als Popup an und bewahren Sie stets die Möglichkeit, die ursprüngliche Eingabe beizubehalten. Fügen Sie der Anfrage Modification=O hinzu, um eine feldweise Aufschlüsselung zu erhalten.

Empfohlene Benutzermeldungen nach Validierungscode

Der Validierungscode (DQECodeDetail in der Classic API, DQEDetailCode in der RESTful API) gibt die Qualität der von der API zurückgegebenen Adresse an. Die folgende Tabelle ordnet jedem Code eine interne Beschreibung (für Support- und Integrationsteams) sowie eine empfohlene Endbenutzermeldung zu.