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

Autovervollständigung - Einzeilig - RESTful

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

Zweistufiger Autovervollständigungs-Ablauf

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

Schritt 1/single/Freitext-Autovervollständigung → Schritt 2/compl/Gebäude- & Wohnungsdetails

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

single

Springen zu Anfrage Parameter Antwort Beispiel Fehler ▶ API testen

RESTful-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 StreetId, die als Eingabe für compl zur Vervollständigung des Gebäudezusatzes dient.

Wann single 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 CheckAddress. Siehe Integrationsleitfaden →

Anfrage

Sowohl GET als auch POST werden unterstützt.

{SERVER_ADDRESS}, {VERSION} 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}/{VERSION}/single/?Address={INPUT}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL-Beispiele

Frankreich - unvollständige Eingabe

curl "https://{SERVER_ADDRESS}/v1/single/?Address=8%20rue%20Victor%20Hugo%20Levall&Country=FRA&Length=38&Limit=20&Version=1&Licence={LICENCE_CODE}"

Japan - Kanji, mit Parameter Langue

curl "https://{SERVER_ADDRESS}/v1/single/?Address=108-6390&Country=JPN&Length=38&Langue=JP&Version=1&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/{VERSION}/single/

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}/v1/single/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "Address=8+rue+Victor+Hugo+Levall" \
  -d "Country=FRA" \
  -d "Length=38" \
  -d "Limit=20" \
  -d "Version=1" \
  -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
Address	`{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
Country	`{COUNTRY_CODE}`	Ländercode nach ISO 3166-1 alpha-3 für den Suchbereich der Adresse. Beispiel: `FRA` oder `GBR`.	Pflicht
Length	`{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
Limit	`{NB}`	Maximale Anzahl zurückgegebener Adressvorschläge. Standard: `20`.	Optional
Version	`1`	Bei `1` wird der Straßentyp aus dem Schlüssel `Street` extrahiert und in einem eigenen Feld `StreetType` zurückgegeben. Ohne diesen Parameter bleibt der Straßentyp Teil von `Street` (z. B. RUE DE LA PAIX) und `StreetType` ist leer.	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 ist die Antwort ein JSON-Objekt mit zwei Schlüsseln auf oberster Ebene: Found (Integer) und Addresses (Array von Adressvorschlags-Objekten, bis zu Limit Einträge). Das erste Ergebnis ist die beste Übereinstimmung mit der Eingabe.

Fachliche Lesart: Betrachten Sie die Antwort als sortierte Liste von Adressvorschlägen. Addresses[0] ist die beste Übereinstimmung; weitere Einträge im Array 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.

Oberste Ebene

Schlüssel	Beschreibung	Typ
Found	Anzahl der zurückgegebenen Adressvorschlags-Objekte.	Integer
Addresses	Array von Adressvorschlags-Objekten.	Array

Adressvorschlags-Objekt - `Addresses[n]`

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)
Street	Straßenname.	String (38)	String (150)
StreetType	Straßentyp (z. B. `RUE`, `AVENUE`, `BOULEVARD`). Nur befüllt, wenn `Version=1` gesetzt ist - in diesem Fall wird der Straßentyp aus `Street` entfernt und stattdessen hier zurückgegeben.	String (20)	String (20)
StreetNumber	Vollständige Hausnummer einschließlich Zusatz (bis, ter usw.).	String (38)	String (38)
StreetNumberOnly	Nur die Hausnummer, ohne Zusatz (bis, ter usw.).	String (4)	String (4)
StreetNumberListCount	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
IsValidStreetNumber	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
StreetNumberList	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)
StreetId	Eindeutige Straßenkennung. Wird als Eingabe für compl verwendet.	String (20)	String (20)
PostalCode	Postleitzahl der Adresse.	String (10)	String (10)
City	Ortsname.	String (38)	String (50)
Hamlet	Flurname oder Weiler (Frankreich) bzw. entsprechendes Feld auf Bezirksebene (international). Die Verfügbarkeit variiert je nach Land.	String (38)	String (50)
SubLocality	Ortsteil (Bezirk, Stadtteil, Vorort).	Leer	String (50)
SpecialDistribution	Nicht in Gebrauch. Wird immer als leere Zeichenkette zurückgegeben.	String	String
CityId	Eindeutige Ortskennung (INSEE-Code für Frankreich).	String (20)	String (20)
StateCode	ISO-Code des Bundesstaats bzw. der Verwaltungsregion (z. B. `17` für Japan).	Leer	String (50)
StateLabel	ISO-Bezeichnung des Bundesstaats bzw. der Verwaltungsregion (z. B. `ISHIKAWA` für Japan).	Nicht verfügbar	String (50)
AdministrativeArea	Landkreis oder gleichwertige Verwaltungsebene.	Leer	String (50)
Suburb	Vorort oder Bezirk.	Leer	String (50)
AdditionalAddress	Zusätzliche Adressinformationen (Gebäudename, Stockwerk usw.). Die Verfügbarkeit variiert je nach Land - siehe Integrationsleitfaden.	Leer	String (50)
Company	Mit der Adresse verknüpfter Firmenname.	String (38)	String (38)
Input	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)
Country	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.	String	String
Longitude	Geokoordinaten der gefundenen Adresse. Nicht für alle Länder verfügbar - siehe Abdeckung.	String	String

Befüllt mit Version=1

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

Antwortbeispiel

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

{
  "Found": 1,
  "Addresses": [
    {
      "PostalCode":           "NW10 7TJ",
      "City":                 "LONDON",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "GBR",
      "StateCode":            "",
      "SubLocality":          "",
      "CityId":               "1745994",
      "Input":                "ABBEY ROAD NW10 7TJ LONDON",
      "Label":                "Abbey Road (West London Waste)|NW10 7TJ LONDON",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "",
      "Street":               "Abbey Road",
      "StreetId":             "7831549_NW107TJ",
      "IsValidStreetNumber":  1,
      "StreetNumberListCount":0,
      "StreetNumberList":     "",
      "StreetNumberOnly":     "",
      "StateLabel":           "",
      "AdministrativeArea":   "",
      "Suburb":               "",
      "Company":              "West London Waste",
      "Latitude":             "",
      "Longitude":            "" }
  ]
}

Japan - Eingabe "三田", Langue=JP

{
  "Found": 20,
  "Addresses": [
    {
      "PostalCode":           "108-6390",
      "City":                 "港区",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "JPN",
      "StateCode":            "13",
      "SubLocality":          "",
      "CityId":               "402573",
      "Input":                "三田",
      "Label":                "〒108-6390 東京都港区三田",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "",
      "Street":               "三田",
      "StreetId":             "558203",
      "IsValidStreetNumber":  1,
      "StreetNumberListCount":0,
      "StreetNumberList":     "",
      "StreetNumberOnly":     "",
      "StateLabel":           "東京都",
      "AdministrativeArea":   "港区",
      "Suburb":               "",
      "Company":              "",
      "Latitude":             "",
      "Longitude":            "" },
    {
      "PostalCode":           "942-0054",
      "City":                 "上越市",
      "Hamlet":               "",
      "SpecialDistribution":  "",
      "Country":              "JPN",
      "StateCode":            "15",
      "SubLocality":          "",
      "CityId":               "387092",
      "Input":                "三田",
      "Label":                "〒942-0054 新潟県上越市三田",
      "AdditionalAddress":    "",
      "StreetNumber":         "",
      "StreetType":           "",
      "Street":               "三田",
      "StreetId":             "537719",
      "IsValidStreetNumber":  1,
      "StreetNumberListCount":0,
      "StreetNumberList":     "",
      "StreetNumberOnly":     "",
      "StateLabel":           "新潟県",
      "AdministrativeArea":   "上越市",
      "Suburb":               "",
      "Company":              "",
      "Latitude":             "",
      "Longitude":            "" }
    // ... 18 weitere Ergebnisse
  ]
}

Fehler

Der RESTful-Endpunkt gibt einen strukturierten JSON-Fehlertext mit HTTP-Statuscode, Meldung und Fehlerkennung zurück.

HTTP	Fehlertyp	Antworttext
400	Parameter `Licence` fehlt	{"status":400,"message":"Missing parameters","details":"Licence","error":"bad request"}
400	Parameter `Licence` leer	{"status":400,"message":"Licence must be filled","details":"Empty","error":"bad request"}
401	Falsche Lizenznummer	{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"{WRONG}","error":"unauthorized_client"}
400	Parameter `Address` fehlt	{"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}
400	Parameter `Country` fehlt	{"status":400,"message":"Missing parameters","details":"Country","error":"bad request"}
400	Parameter `Country` leer	{"status":400,"message":"Country must be filled","details":"Empty","error":"bad request"}
400	Tippfehler im Parameternamen	{"status":400,"message":"Missing parameters","details":"Address","error":"bad request"}

API testen

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

Konsole öffnen

compl

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 single-Ergebnis ausgewählt wurden, wird eine Liste von Gebäudezusatz-Vorschlägen zurückgegeben: Gebäudenamen, Stockwerke, Firmennamen, Wohnungsnummern.

Wann compl verwenden? Verwenden Sie compl, nachdem der Nutzer eine Straße aus single ausgewählt hat. Übergeben Sie die von single zurückgegebenen Werte StreetId und StreetNumber, 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}, {VERSION} und {LICENCE_CODE} werden von DQE bei der Kontoeröffnung bereitgestellt. {STREETID} stammt aus der single-Antwort. Wenden Sie sich an Ihren DQE-Ansprechpartner, um diese Zugangsdaten zu erhalten.

GET POST

GEThttps://{SERVER_ADDRESS}/{VERSION}/compl/?StreetId={STREETID}&StreetNumber={STREETNUMBER}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}

cURL-Beispiel

Frankreich

curl "https://{SERVER_ADDRESS}/v1/compl/?StreetId=1454602&StreetNumber=20&Country=FRA&Licence={LICENCE_CODE}"

POSThttps://{SERVER_ADDRESS}/{VERSION}/compl/

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}/v1/compl/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "StreetId=1454602" \
  -d "StreetNumber=20" \
  -d "Country=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
StreetId	`{STREETID}`	Eindeutige Straßenkennung, die von single im Feld `StreetId` zurückgegeben wird.	Pflicht
StreetNumber	`{STREETNUMBER}`	Vom Nutzer ausgewählte Hausnummer - entspricht dem Feld `StreetNumber` aus der single-Antwort.	Pflicht
Country	`{COUNTRY_CODE}`	Ländercode nach ISO 3166-1 alpha-3 für den Suchbereich der Adresse. Beispiel: `FRA` oder `GBR`.	Pflicht
Length	`{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
Search	`{SEARCH}`	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 ist die Antwort ein JSON-Objekt mit zwei Schlüsseln auf oberster Ebene: Found und AdditionalAddresses (Array) sowie einem Objekt Geolocalisation. Die Geokodierungsabdeckung variiert je nach Land - siehe Geografische Abdeckung.

Fehlende Gebäudezusatzdaten sind kein Fehler. Siehe Integrationsleitfaden →

Schlüssel	Beschreibung	Frankreich	International
Found	Anzahl der gefundenen Adresszusätze.	Integer	Integer
AdditionalAddresses	Array von Adresszusatz-Objekten.	Array	Array
AdditionalAddresses[0]. AdditionalAddress	Zusätzliche Adressbezeichnung (Gebäudename, Stockwerk, Wohnung usw.).	String (38)	String (150)
AdditionalAddresses[0]. PostalCode	Für diese Untereinheit spezifische Postleitzahl, sofern verfügbar (z. B. ZIP+4 für die USA).	Leer	String (10)
Geolocalisation	Geolokalisierungsinformationen zur Adresse.	Object	Object
Geolocalisation. Latitude	Geokoordinaten der gefundenen Adresse. Nicht für alle Länder verfügbar - siehe Abdeckung.	String	String
Geolocalisation. Longitude	Geokoordinaten der gefundenen Adresse. Nicht für alle Länder verfügbar - siehe Abdeckung.	String	String

Antwortbeispiel

Frankreich

{
  "Found": 5,
  "AdditionalAddresses": [
    { "AdditionalAddress": "BATIMENT A", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT B", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT C", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT D", "PostalCode": "" },
    { "AdditionalAddress": "BATIMENT E", "PostalCode": "" }
  ],
  "Geolocalisation": {
    "Latitude":  "48.879024",
    "Longitude": "2.333291" }
}

Fehler

HTTP	Fehlertyp	Antworttext
400	`StreetId` fehlt	{"status":400,"message":"Missing parameters","details":"StreetId","error":"bad request"}
400	`StreetNumber` fehlt	{"status":400,"message":"Missing parameters","details":"StreetNumber","error":"bad request"}
400	`Country` fehlt	{"status":400,"message":"Missing parameters","details":"Country","error":"bad request"}
400	`Licence` fehlt	{"status":400,"message":"Missing parameters","details":"Licence","error":"bad request"}
401	Nicht autorisierter Client (Lizenz ungültig, abgelaufen oder außerhalb des Leistungsumfangs)	{"status":401,"message":"Your licence is not allowed to cover this functionnality","details":"{INVALID_LICENCE}","error":"unauthorized_client"}

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 (RESTful)

single

Anfrage

cURL-Beispiele

cURL-Beispiel

Parameter

Antwort

Oberste Ebene

Adressvorschlags-Objekt - `Addresses[n]`

Antwortbeispiel

Fehler

API testen

compl

Anfrage

cURL-Beispiel

cURL-Beispiel

Parameter

Antwort

Antwortbeispiel

Fehler

API testen

Siehe auch

War dieser Beitrag hilfreich?

Vorheriger Artikel

Nächster Artikel

single

Anfrage

cURL-Beispiele

cURL-Beispiel

Parameter

Antwort

Oberste Ebene

Adressvorschlags-Objekt - Addresses[n]

Antwortbeispiel

Fehler

API testen

compl

Anfrage

cURL-Beispiel

cURL-Beispiel

Parameter

Antwort

Antwortbeispiel

Fehler

API testen

Siehe auch

War dieser Beitrag hilfreich?

Vorheriger Artikel

Nächster Artikel

Adressvorschlags-Objekt - `Addresses[n]`