Address API - Autovervollständigung aus einer einzelnen Zeile (Classic)

Autovervollständigung - Einzeilig - Standard-API

Zweistufige Adress-Autovervollständigung über die Classic-API: SINGLEV2 liefert aus einer Freitexteingabe eine nach Relevanz sortierte Liste von Adressvorschlägen; COMPLV2 ruft nach der Auswahl eines Vorschlags die Gebäudezusatz-Optionen ab.

Zweistufiger Autovervollständigungs-Ablauf

Der Nutzer tippt frei; SINGLEV2 liefert in Echtzeit sortierte Vorschläge. Nach der Auswahl ruft COMPLV2 die Gebäudezusatz-Optionen ab (Gebäudenamen, Stockwerke, Wohnungsnummern).

Schritt 1/SINGLEV2/Freitext-Autovervollständigung → Schritt 2/COMPLV2/Gebäude- & Wohnungsdetails

Groß-/Kleinschreibung der Ausgabe - Die Schreibweise folgt der Postnorm des jeweiligen Landes.

SINGLEV2

Springen zu Anfrage Parameter Antwort Beispiel Fehler ▶ API testen

Standard-API-Endpunkt für die Adress-Autovervollständigung. Akzeptiert unvollständige oder vollständige Freitexteingaben und liefert eine sortierte Liste von Adressvorschlägen. Jeder Vorschlag enthält eine IDVoie, die als Eingabe für COMPLV2 zur Vervollständigung des Gebäudezusatzes dient.

Wann SINGLEV2 verwenden? Verwenden Sie diesen Endpunkt, um während der Eingabe Adressen vorzuschlagen. Er verarbeitet unvollständige Eingaben (Straßenfragment, Postleitzahl, Ortsname) und liefert alle strukturierten Felder, um ein Formular direkt zu befüllen. Um zu prüfen, ob eine bereits vollständige Adresse gültig und zustellbar ist, verwenden Sie stattdessen RNVP. Siehe Integrationsleitfaden →

Anfrage

Sowohl GET als auch POST werden unterstützt.

{SERVER_ADDRESS} und {LICENCE_CODE} werden von DQE bei der Kontoeröffnung bereitgestellt. Wenden Sie sich an Ihren DQE-Ansprechpartner, um diese Zugangsdaten zu erhalten.

Die Adresseingabe muss URL-kodiert sein - z. B. l'église → l%27%C3%A9glise.

GET POST

GEThttps://{SERVER_ADDRESS}/SINGLEV2/?Adresse={INPUT}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL-Beispiele

Frankreich - unvollständige Eingabe

curl "https://{SERVER_ADDRESS}/SINGLEV2/?Adresse=8%20rue%20Victor%20Hugo%20Levall&Pays=FRA&Licence={LICENCE_CODE}&Taille=38&NbMax=20&Version=1"

Japan - Kanji, mit Parameter Langue

curl "https://{SERVER_ADDRESS}/SINGLEV2/?Adresse=108-6390&Pays=JPN&Taille=38&Langue=JP&Version=1&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/SINGLEV2/

Senden Sie alle Parameter im Anfragetext mit Content-Type: application/x-www-form-urlencoded. Die Serveradresse bleibt in der URL.

cURL-Beispiel

Frankreich - unvollständige Eingabe

curl -X POST "https://{SERVER_ADDRESS}/SINGLEV2/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "Adresse=8+rue+Victor+Hugo+Levall" \
  -d "Pays=FRA" \
  -d "Licence={LICENCE_CODE}" \
  -d "Taille=38" \
  -d "NbMax=20" \
  -d "Version=1"

Parameter

Parameter	Wert	Beschreibung	Pflicht / Opt.
Licence	`{LICENCE_CODE}`	Ihr DQE-Lizenzschlüssel oder OAuth2-Token. Wenden Sie sich an den Support, falls Sie noch keinen haben.	Pflicht
Adresse	`{INPUT}`	Vom Nutzer eingegebene Freitext-Adresse. Akzeptiert unvollständige Eingaben - Straßenfragment, Hausnummer, Postleitzahl oder Ortsname. Muss URL-kodiert sein. Kein Pipe-Format erforderlich - übergeben Sie die Zeichenkette so, wie sie eingegeben wurde.	Pflicht
Pays	`{COUNTRY_CODE}`	Ländercode nach ISO 3166-1 alpha-3 für den Suchbereich der Adresse. Beispiel: `FRA` oder `GBR`.	Pflicht
Taille	`{LENGTH}`	Maximale Zeichenlänge der zurückgegebenen Adressvorschläge. Gilt nur für Adressen in lateinischer Schrift. Ein zu niedriger Wert kann die Ergebnisse abschneiden. Standard: `38`. Empfohlenes Minimum: `32`.	Optional
NbMax	`{NB}`	Maximale Anzahl zurückgegebener Adressvorschläge. Standard: `20`.	Optional
Version	`1`	Bei `1` wird der Straßentyp aus dem Schlüssel `Voie` extrahiert und in einem eigenen Feld `TypeVoie` zurückgegeben. Ohne diesen Parameter bleibt der Straßentyp Teil von `Voie` (z. B. RUE DE LA PAIX) und `TypeVoie` ist leer.	Optional
Instance	`{INSTANCE}`	Wird bei diesem Endpunkt nicht in den Ergebnissen zurückgegeben - kann weggelassen werden.	Optional
Langue	`{LANGUAGE}`	Filtert die Ergebnisse nach Sprache/Schrift (z. B. JPN: `JP` = Kanji · `JK` = Katakana · `EN` = lateinische Umschrift). Siehe Sprachleitfaden.	Optional
Filter	`{FILTER}`	Nur Frankreich. Filtert CEDEX-Adressen: `1` alle Adressen; `2` nur Nicht-CEDEX; `3` nur CEDEX.	Optional

Antwort

Bei Erfolg gibt die API ein JSON-Objekt zurück. Die Schlüssel sind Rangnummern von "1" bis "n", die jeweils auf ein Wörterbuch mit Adressfeldern verweisen. Das erste Ergebnis ist die beste Übereinstimmung mit der Eingabe.

Fachliche Lesart: Betrachten Sie die Antwort als sortierte Liste von Adressvorschlägen. "1" ist die beste Übereinstimmung; höhere Nummern sind alternative Kandidaten. Das Feld label enthält die anzeigefertige Zeichenkette für Ihre Autovervollständigungsliste - alle anderen Felder liefern die strukturierten Bestandteile zum Befüllen der Formularfelder.

Schlüssel	Beschreibung	Frankreich	International
label	Anzeigefertige Zeichenkette für eine Autovervollständigungsliste. Nummern in `[eckigen Klammern]` bedeuten, dass die Nummer in den Referenzdaten nicht gefunden wurde. Hinweise zur Verwendung siehe Feld label - nur zur Anzeige. Verwenden Sie `label` nur zum Befüllen der Vorschlagsliste - niemals zum Speichern der Adresse. Siehe Integrationsleitfaden →	String (255)	String (255)
Voie	Straßenname.	String (38)	String (150)
TypeVoie	Straßentyp (z. B. `RUE`, `AVENUE`, `BOULEVARD`). Nur befüllt, wenn `Version=1` gesetzt ist - in diesem Fall wird der Straßentyp aus `Voie` entfernt und stattdessen hier zurückgegeben.	String (20)	String (20)
Numero	Vollständige Hausnummer einschließlich Zusatz (bis, ter usw.).	String (38)	String (38)
Num	Alias für `Numero`. Aus Kompatibilitätsgründen beibehalten - bevorzugen Sie `Numero`.	String (38)	String (38)
NumSeul	Nur die Hausnummer, ohne Zusatz (bis, ter usw.).	String (4)	String (4)
NbNumero auch: Nbnumero	Wenn die abgefragte Nummer nicht gefunden wurde oder fehlt, wird die Gesamtzahl der gültigen Hausnummern dieser Straße zurückgegeben. Kann bei manchen internationalen Adressen, für die diese Daten nicht verfügbar sind, eine leere Zeichenkette sein.	String	String
valid_num	Gültigkeitsindikator der Hausnummer. `1`, wenn die Nummer in den Referenzdaten existiert, sonst `0`. Gibt bei manchen internationalen Adressen, für die keine Validierung auf Hausnummernebene verfügbar ist, eine leere Zeichenkette zurück.	Integer	Integer
ListeNumero	Durch Semikolons getrennte Liste gültiger Hausnummern. Enthält alle Nummern, wenn keine Nummer eingegeben wurde oder die eingegebene Nummer nicht gefunden wurde; andernfalls nur die gefundene Nummer.	String (1024)	String (1024)
IDVoie auch: CodeVoie	Eindeutige Straßenkennung. Wird als Eingabe für COMPLV2 verwendet. CodeVoie wird aus Kompatibilitätsgründen beibehalten. Bevorzugen Sie IDVoie in neuen Integrationen.	String (20)	String (20)
CodePostal	Postleitzahl der Adresse.	String (10)	String (10)
Localite	Ortsname.	String (38)	String (50)
SousLocalite	Ortsteil (Bezirk, Stadtteil, Vorort).	Leer	String (50)
LieuDit	Flurname oder Weiler (Frankreich) bzw. entsprechendes Feld auf Bezirksebene (international). Die Verfügbarkeit variiert je nach Land.	String (38)	String (50)
IDLocalite	Eindeutige Ortskennung (INSEE-Code für Frankreich).	String (20)	String (20)
Province	ISO-Code des Bundesstaats bzw. der Verwaltungsregion (z. B. `17` für Japan).	Nicht verfügbar	String (50)
Region1	ISO-Bezeichnung des Bundesstaats bzw. der Verwaltungsregion (z. B. `ISHIKAWA` für Japan).	Nicht verfügbar	String (50)
Region2	Landkreis oder gleichwertige Verwaltungsebene.	Nicht verfügbar	String (50)
Region3	Landkreis oder Gleichwertiges (alternative Ebene).	Nicht verfügbar	String (50)
Region4	Zusätzliche regionale oder administrative Informationen.	Nicht verfügbar	String (50)
Suburb	Vorort oder Bezirk.	Nicht verfügbar	String (50)
Complement	Zusätzliche Adressinformationen (Gebäudename, Stockwerk usw.). Die Verfügbarkeit variiert je nach Land - siehe Integrationsleitfaden.	Leer	String (50)
Complement2	Zweite Gebäudezusatzzeile. Befüllt bei bestimmten internationalen Adressen, wenn sowohl eine Gebäudekennung als auch eine Untereinheitskennung (Stockwerk, Wohnung, Suite) als separate Einträge verfügbar sind, sowie bei bestimmten CEDEX-Adressen von Organisationen.	Nicht verfügbar	String (50)
Entreprise	Mit der Adresse verknüpfter Firmenname.	String (38)	String (38)
Thoroughfare	Abhängige Straße.	Nicht verfügbar	Nur UK
Pays	Ländercode nach ISO 3166-1 alpha-3.	String (3)	String (3)
Latitude	Geokoordinaten der gefundenen Adresse. Nicht für alle Länder verfügbar - siehe Abdeckung.	Nicht verfügbar	String
Longitude	Geokoordinaten der gefundenen Adresse. Nicht für alle Länder verfügbar - siehe Abdeckung.	Nicht verfügbar	String
Saisie	Normalisierte Form der übermittelten Adresse. Kann in Schreibweise oder Formatierung von der ursprünglichen Eingabe abweichen. Nicht für alle Länder befüllt.	String (255)	String (255)
Instance	Internes Feld.	Leer	String

Befüllt mit Version=1

Straße ohne Hausnummer ausgewählt? Siehe Integrationsleitfaden →

Antwortbeispiel

Vereinigtes Königreich - Eingabe "Abbey Road NW10 7TJ London"

{
  "1": {
    "label":        "Abbey Road (West London Waste)|NW10 7TJ LONDON",
    "valid_num":    1,
    "Num":          "",
    "Numero":       "",
    "ListeNumero":  "",
    "Nbnumero":     0,
    "NbNumero":     0,
    "NumSeul":      "",
    "Saisie":       "ABBEY ROAD NW10 7TJ LONDON",
    "Pays":         "GBR",
    "Complement":   "",
    "Voie":         "Abbey Road",
    "CodeVoie":     "7831549_NW107TJ",
    "IDVoie":       "7831549_NW107TJ",
    "IDLocalite":   "1745994",
    "Instance":     1,
    "CodePostal":   "NW10 7TJ",
    "Localite":     "LONDON",
    "Province":     "",
    "LieuDit":      "",
    "Longitude":    "",
    "Latitude":     "",
    "Suburb":       "",
    "TypeVoie":     "",
    "Entreprise":   "West London Waste",
    "Thoroughfare": ""
  }
}

Japan - Eingabe "三田", Langue=JP

{
  "1": {
    "label":        "〒108-6390 東京都港区三田",
    "valid_num":    1,
    "Num":          "",
    "Numero":       "",
    "ListeNumero":  "",
    "Nbnumero":     0,
    "NbNumero":     0,
    "NumSeul":      "",
    "Saisie":       "三田",
    "Pays":         "JPN",
    "Complement":   "",
    "Voie":         "三田",
    "CodeVoie":     "558203",
    "IDVoie":       "558203",
    "IDLocalite":   "402573",
    "Instance":     1,
    "CodePostal":   "108-6390",
    "Localite":     "港区",
    "Province":     "13",
    "LieuDit":      "",
    "Longitude":    "",
    "Latitude":     "",
    "Region1":      "東京都",
    "Region2":      "港区",
    "Region3":      "",
    "Suburb":       "",
    "TypeVoie":     ""
  },
  "2": {
    "label":        "〒942-0054 新潟県上越市三田",
    "valid_num":    1,
    "Num":          "",
    "Numero":       "",
    "ListeNumero":  "",
    "Nbnumero":     0,
    "NbNumero":     0,
    "NumSeul":      "",
    "Saisie":       "三田",
    "Pays":         "JPN",
    "Complement":   "",
    "Voie":         "三田",
    "CodeVoie":     "537719",
    "IDVoie":       "537719",
    "IDLocalite":   "387092",
    "Instance":     1,
    "CodePostal":   "942-0054",
    "Localite":     "上越市",
    "Province":     "15",
    "LieuDit":      "",
    "Longitude":    "",
    "Latitude":     "",
    "Region1":      "新潟県",
    "Region2":      "上越市",
    "Region3":      "",
    "Suburb":       "",
    "TypeVoie":     ""
  }
  // ... 18 weitere Ergebnisse
}

Fehler

HTTP	Fehlertyp	Antworttext
400	`Licence` fehlt oder ist leer	`Bad Request Parameters empty fields`
401	Ungültiger oder nicht autorisierter Lizenzschlüssel	`unauthorized_client`
400	`Adresse` fehlt oder ist leer	`Bad Request Parameters empty fields`
400	`Pays` fehlt oder ist leer	`Bad Request Parameters empty fields`
400	Unbekannter Parametername (z. B. Tippfehler in `Adresse`)	`Bad Request Parameters empty fields`

API testen

Klicken Sie auf die Schaltfläche unten, um diesen Endpunkt live in Ihrem Browser zu testen.

Konsole öffnen

COMPLV2

Springen zu Anfrage Parameter Antwort Beispiel Fehler ▶ API testen

Zweiter Schritt des einzeiligen Ansatzes. Anhand einer Straßen-ID und einer Hausnummer, die aus einem SINGLEV2-Ergebnis ausgewählt wurden, wird eine Liste von Gebäudezusatz-Vorschlägen zurückgegeben: Gebäudenamen, Stockwerke, Firmennamen, Wohnungsnummern.

Wann COMPLV2 verwenden? Verwenden Sie COMPLV2, nachdem der Nutzer eine Straße aus SINGLEV2 ausgewählt hat. Übergeben Sie die von SINGLEV2 zurückgegebenen Werte IDVoie und IDNum, um detaillierte Gebäudezusatz-Optionen zu erhalten. Wenn für die Adresse keine Gebäudezusatz-Optionen existieren, werden keine nummerierten Einträge zurückgegeben.

Anfrage

Sowohl GET als auch POST werden unterstützt.

{SERVER_ADDRESS} und {LICENCE_CODE} werden von DQE bei der Kontoeröffnung bereitgestellt. {STREET_ID} stammt aus der SINGLEV2-Antwort. Wenden Sie sich an Ihren DQE-Ansprechpartner, um diese Zugangsdaten zu erhalten.

GET POST

GEThttps://{SERVER_ADDRESS}/COMPLV2/?IDVoie={STREET_ID}&IDNum={NUM}&Pays={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL-Beispiel

Frankreich

curl "https://{SERVER_ADDRESS}/COMPLV2/?IDVoie=1454602&IDNum=20&Pays=FRA&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/COMPLV2/

Senden Sie alle Parameter im Anfragetext mit Content-Type: application/x-www-form-urlencoded. Die Serveradresse bleibt in der URL.

cURL-Beispiel

Frankreich

curl -X POST "https://{SERVER_ADDRESS}/COMPLV2/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "IDVoie=1454602" \
  -d "IDNum=20" \
  -d "Pays=FRA" \
  -d "Licence={LICENCE_CODE}"

Parameter

Parameter	Wert	Beschreibung	Pflicht / Opt.
Licence	`{LICENCE_CODE}`	Ihr DQE-Lizenzschlüssel oder OAuth2-Token. Wenden Sie sich an den Support, falls Sie noch keinen haben.	Pflicht
IDVoie	`{STREETID}`	Eindeutige Straßenkennung, die von SINGLEV2 im Feld `IDVoie` oder `CodeVoie` zurückgegeben wird.	Pflicht
IDNum	`{STREETNUMBER}`	Vom Nutzer ausgewählte Hausnummer - entspricht dem Feld `Numero` aus der SINGLEV2-Antwort.	Pflicht
Pays	`{COUNTRY_CODE}`	Ländercode nach ISO 3166-1 alpha-3 für den Suchbereich der Adresse. Beispiel: `FRA` oder `GBR`.	Pflicht
Taille	`{LENGTH}`	Maximale Zeichenlänge der zurückgegebenen Adressfelder. Gilt nur für Adressen in lateinischer Schrift. Ein zu niedriger Wert kann die Ergebnisse abschneiden. Standard: `38`. Empfohlenes Minimum: `32`.	Optional
Filter	`{FILTER}`	Für die Vereinigten Staaten: filtert die Zusatzvorschläge anhand dessen, was der Nutzer eingegeben hat. Übergeben Sie den eingegebenen Teil des Zusatztyps (z. B. `FL`, `STE`, `RM`) - nur passende Zusatzeinträge werden zurückgegeben.	Optional

Antwort

Bei Erfolg gibt die API ein JSON-Objekt mit zwei Arten von Schlüsseln zurück. Nummerierte Schlüssel ("1" bis "n") stehen jeweils für eine Gebäudezusatz-Option. Geografische Schlüssel auf oberster Ebene (Latitude, Longitude) liefern die Geokoordinaten der gefundenen Adresse. Die Geokodierungsabdeckung variiert je nach Land - siehe Geografische Abdeckung.

Fehlende Gebäudezusatzdaten sind kein Fehler. Siehe Integrationsleitfaden →

Schlüssel	Beschreibung	Frankreich	International
Nummerierte Einträge ("1" bis "n") - einer pro Gebäudezusatz-Option
Batiment	Zusätzliche Adressbezeichnung (Gebäudename, Stockwerk, Wohnung usw.).	String (38)	String (150)
CodePostal	Für diese Untereinheit spezifische Postleitzahl, sofern verfügbar (z. B. ZIP+4 für die USA).	Nicht verfügbar	String (10)
Geografische Felder auf oberster Ebene
Latitude	Geokoordinaten der gefundenen Adresse. Nicht für alle Länder verfügbar - siehe Abdeckung.	String	String
Longitude	Geokoordinaten der gefundenen Adresse. Nicht für alle Länder verfügbar - siehe Abdeckung.	String	String
Oberste Ebene - optional, nur Frankreich (erfordert ein Iris/Ilot-Abonnement)
Status_IrisIlot	Quelle der IRIS/Ilot-Codes (z. B. `INSEE`).	String (5)	Nicht verfügbar
ilot	Îlot-Code.	String (9)	Nicht verfügbar
iris	IRIS-Code.	String (9)	Nicht verfügbar

Antwortbeispiel

Frankreich

{
  "1": { "Batiment": "BATIMENT A" },
  "2": { "Batiment": "BATIMENT B" },
  "3": { "Batiment": "BATIMENT C" },
  "4": { "Batiment": "BATIMENT D" },
  "5": { "Batiment": "BATIMENT E" },
  "Latitude":  "48.879024",
  "Longitude": "2.333291"
}

Fehler

HTTP	Fehlertyp	Antworttext
400	`Licence` fehlt oder ist leer	`Bad Request Parameters empty fields`
500	Ungültiger oder nicht autorisierter Lizenzschlüssel	`{}` (leeres JSON-Objekt)
400	`IDVoie` fehlt	`400 Bad Request`
400	`Pays` fehlt	`400 Bad Request`
400	Tippfehler im Parameternamen (unbekannter Schlüssel)	`400 Bad Request`

API testen

Klicken Sie auf die Schaltfläche unten, um diesen Endpunkt live in Ihrem Browser zu testen.

Konsole öffnen

Address API - Autovervollständigung aus einer einzelnen Zeile (Classic)

SINGLEV2

Anfrage

cURL-Beispiele

cURL-Beispiel

Parameter

Antwort

Antwortbeispiel

Fehler

API testen

COMPLV2

Anfrage

cURL-Beispiel

cURL-Beispiel

Parameter

Antwort

Antwortbeispiel

Fehler

API testen

Siehe auch

War dieser Beitrag hilfreich?

Vorheriger Artikel

Nächster Artikel