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.
| Regel | Format | Länder |
|---|---|---|
| Nummer vor Straße | Numero Voie |
AND · ARM · ATG · AUS · AZE · BEN · BFA · BGD · BHR · BLM und 89 weitereBLZ · BMU · BRB · BRN · CAN · CHN · CIV · COD · COG · COK · CYM · DJI · DMA · DZA · EGY · FJI · FRA · FSM · GAB · GBR · GHA · GIB · GIN · GMB · GUY · HKG · IND · IRL · JAM · JPN · KEN · KHM · KNA · KOR · KWT · LAO · LBN · LKA · LSO · LUX · MAF · MAR · MCO · MDG · MDV · MHL · MLT · MMR · MNP · MRT · MSR · MUS · MWI · MYS · NAM · NGA · NIU · NRU · NZL · OMN · PAK · PHL · PNG · RWA · SAU · SEN · SGP · SHN · SLE · SYC · TCA · TGO · THA · TKM · TON · TTO · TUN · TUV · TWN · TZA · UGA · USA · VGB · VNM · XKX · YEM · ZAF · ZMB · ZWE |
| Straße vor Nummer | Voie Numero |
ABW · AFG · AGO · AIA · ALA · ALB · ARG · AUT · BDI · BEL und 103 weitereBES · BGR · BHS · BIH · BLR · BOL · BRA · BTN · BWA · CAF · CHE · CHL · CMR · COL · COM · CPV · CRI · CUB · CUW · CYP · CZE · DEU · DNK · DOM · ECU · ERI · ESH · ESP · EST · ETH · FIN · FRO · GEO · GNB · GNQ · GRC · GRD · GRL · GTM · HND · HRV · HTI · HUN · IDN · ISL · ISR · ITA · JOR · KAZ · KGZ · KIR · LBR · LBY · LCA · LTU · LVA · MAC · MDA · MEX · MKD · MLI · MNE · MOZ · NIC · NLD · NOR · NPL · PAN · PER · PLW · POL · PRK · PRT · PRY · QAT · ROU · RUS · SDN · SLB · SLV · SMR · SOM · SRB · SSD · STP · SUR · SVK · SVN · SWE · SWZ · SXM · SYR · TCD · TJK · TLS · TUR · UKR · URY · UZB · VCT · VEN · VUT · WSM |
Voie in lokaler Schrift zurückgegeben werden. In diesem Fall verwenden Sie Voie Numero unabhängig von der obigen Regel. Erkennen Sie dies, indem Sie prüfen, ob Voie nicht-lateinische Zeichen enthält.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
| Feld | Wert | Bedeutung |
|---|---|---|
| valid_num | "0" |
Keine gültige Nummer gefunden |
| ListeNumero | nicht leer | Bekannte Nummern existieren für diese Straße |
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
| Land | Unterstützte Werte | Wirkung |
|---|---|---|
| Japan (JPN) |
JP · JK · EN
|
JP = Kanji · JK = Katakana · EN = Romaji. Ohne Langue werden alle drei Schriften zurückgegeben. |
| Hongkong (HKG) |
EN · ZH
|
EN = Englisch · ZH = Chinesisch. Wird Langue=EN bei chinesischer Eingabe gesetzt (oder umgekehrt), werden null Ergebnisse zurückgegeben. |
| Thailand (THA) |
EN · TH
|
EN = lateinische Transliteration · TH = thailändische Schrift. Ohne Langue werden beide Sprachversionen gleichzeitig zurückgegeben (z. B. gibt eine Suche nach Postleitzahl gemischte thailändische und englische Ergebnisse zurück). |
Langue mit keinem Eintrag in der Datenbank für eine bestimmte Eingabe übereinstimmt, gibt die API null Ergebnisse zurück. Stellen Sie sicher, dass die angeforderte Sprache mit der Schrift der eingegebenen Adresse übereinstimmt.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.
| Schlüssel | Beschreibung | Werte |
|---|---|---|
| Status_Modification RESTful: IsAddressChanged |
Gibt an, ob DQE die Adresse geändert hat. |
O / N (Classic) · 1 / 0 (RESTful) |
| Code_Modification RESTful: ChangedAddressTag |
5-stellige Binärzeichenfolge - eine Position pro Feld (zusätzliche Adresse · Adresse · abhängiger Ort · Postleitzahl · Stadt). Siehe CheckAddress-Referenz. Beispiel: 00011
|
5-stellig binär |
| DQECodeDetail RESTful: DQEDetailCode |
Validierungsergebniscode der von DQE zurückgegebenen Adresse - nicht der ursprünglichen Benutzereingabe. Beispiel: Eingabe 12 RUE PAIX PARIS → DQE gibt 12 RUE DE LA PAIX 75002 PARIS mit DQECodeDetail=10 (gültig) zurück. Vollständige Liste mit empfohlenen UI-Meldungen in der CheckAddress-Referenz. |
Numerischer Code |
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.
| Code | Beschreibung | Interne Beschreibung | UI-Anzeige |
|---|---|---|---|
| 10 | Korrekte Adresse | Gültige Adresse | Gültige Adresse |
| 20 | Korrekte Adresse (Straße nicht erkannt, aber es handelt sich um ein CEDEX oder ein Postfach) | Gültige Adresse | Gültige Adresse |
| 21 | Kleinstadt, Hausnummer außerhalb des gültigen Bereichs | Bitte die Adresse mit dem Kunden bestätigen (Hausnummer existiert nicht) | Bitte überprüfen Sie Ihre Postadresse |
| 22 | Kleinstadt, Hausnummer fehlt (der Rest der Adresse ist korrekt) | Bitte die Adresse mit dem Kunden bestätigen (Hausnummer fehlt) | Bitte überprüfen Sie Ihre Postadresse |
| 23 | Großstadt, Hausnummer außerhalb des gültigen Bereichs | Bitte die Adresse mit dem Kunden bestätigen (Hausnummer existiert nicht) | Bitte überprüfen Sie Ihre Postadresse |
| 24 | Großstadt, Hausnummer fehlt (der Rest der Adresse ist korrekt) | Bitte die Adresse mit dem Kunden bestätigen (Hausnummer fehlt) | Bitte überprüfen Sie Ihre Postadresse |
| 25 | CEDEX-Adresse CEDEXA unbekannt (wenn CEDEXA aktiv ist) | Gültige Adresse | Gültige Adresse |
| 30 | Kleinstadt, Straße nicht erkannt | Bitte die Adresse mit dem Kunden bestätigen (Straßenname nicht gefunden) | Bitte überprüfen Sie Ihre Postadresse |
| 31 | Kleinstadt - Straße nicht erkannt oder fehlt; Bezirksinformation erkannt, aber nicht ausreichend, um die Straße zu bestimmen. Nur Frankreich. | Bitte die Adresse mit dem Kunden bestätigen (Straßenname nicht gefunden) | Bitte überprüfen Sie Ihre Postadresse |
| 40 | In aktuellen Cloud-Bereitstellungen nicht erwartet. Aus Kompatibilitätsgründen definiert. | - | - |
| 41 | Kleinstadt, Straße fehlt | Bitte die Adresse mit dem Kunden bestätigen (Straßenname fehlt) | Bitte überprüfen Sie Ihre Postadresse |
| 50 | Großstadt, Straße nicht erkannt | Bitte die Adresse mit dem Kunden bestätigen (Straßenname nicht gefunden) | Bitte überprüfen Sie Ihre Postadresse |
| 51 | Großstadt - Straße nicht erkannt oder fehlt (Bezirksinformation erkannt, aber nicht ausreichend, um die Straße zu bestimmen). Nur Frankreich. | Bitte die Adresse mit dem Kunden bestätigen (Straßenname nicht gefunden) | Bitte überprüfen Sie Ihre Postadresse |
| 60 | In aktuellen Cloud-Bereitstellungen nicht erwartet. Aus Kompatibilitätsgründen definiert. | - | - |
| 61 | Großstadt, Straße fehlt | Bitte die Adresse mit dem Kunden bestätigen (Straßenname fehlt) | Bitte überprüfen Sie Ihre Postadresse |
| 70 | Postleitzahl/Stadt stimmen nicht überein - Straße vorhanden | Die Adresse ist falsch. Postleitzahl/Stadt stimmen nicht überein. | Bitte überprüfen Sie Ihre Postadresse |
| 71 | In aktuellen Cloud-Bereitstellungen nicht erwartet. Aus Kompatibilitätsgründen definiert. | - | - |
| 80 | Postleitzahl/Stadt stimmen nicht überein - Straße fehlt | Die Adresse ist falsch. Postleitzahl/Stadt stimmen nicht überein. | Bitte überprüfen Sie Ihre Postadresse |
| 81 | Eingegebener Adressblock leer. Wird für Frankreich nicht zurückgegeben. | Adresse nicht ausgefüllt | Bitte überprüfen Sie Ihre Postadresse |
| 90 | Internationale Adresse erkannt - der eingegebene Ländercode scheint nicht mit der eingegebenen Adresse übereinzustimmen. | Adresse erscheint international - Ländercode stimmt nicht überein | Bitte überprüfen Sie Ihre Postadresse |
| 95 | Fehlender oder falscher Ländercode | Ländercode in der Eingabe prüfen und korrigieren | Bitte überprüfen Sie Ihre Postadresse |
Verknüpfung mit