Trichter-Autovervollständigung - RESTful
Die RESTful-Endpunkte funnelpostcode / funneladdress / funnelcompl ermöglichen eine geführte, postleitzahlbasierte Autovervollständigung: Eingrenzung auf eine Stadt, Auflistung ihrer Straßen und anschließendes Abrufen der Gebäudeteil-Details für die gewählte Adresse.
Dreistufiger Autovervollständigungsablauf
Groß-/Kleinschreibung der Ausgabe - Die
Schreibweise folgt der Postnorm des jeweiligen Landes.
Stadtauswahl (funnelpostcode)
Erster Schritt des Trichter-Ansatzes. Gibt passende Städte
und Postleitzahlen anhand einer teilweisen oder vollständigen
Postleitzahl- oder Ortsnamenseingabe zurück. Das Feld
CityId aus jedem Ergebnis dient als
Eingabe für den nächsten Schritt: funneladdress.
Anfrage
funnelpostcode unterstützt sowohl GET als auch POST.
{SERVER_ADDRESS}, {VERSION}
und {LICENCE_CODE} werden von DQE bei
der Kontoerstellung bereitgestellt. Wenden Sie sich an
Ihren DQE-Kundenbetreuer, um diese Zugangsdaten zu erhalten.
GEThttps://{SERVER_ADDRESS}/{VERSION}/funnelpostcode/?PostalCode={POSTAL_CODE}&Country={COUNTRY_CODE}&Licence={LICENCE_CODE}
cURL-Beispiel
Frankreich - Suche nach Postleitzahl
curl "https://{SERVER_ADDRESS}/v1/funnelpostcode/?PostalCode=75008&Country=FRA&Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/funnelpostcode/?"
+ new URLSearchParams({
PostalCode: "75008",
Country: "FRA",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/v1/funnelpostcode/",
params={
"PostalCode": "75008",
"Country": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'PostalCode' => '75008',
'Country' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funnelpostcode/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/v1/funnelpostcode/',
{
params: {
PostalCode: '75008',
Country: 'FRA',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/v1/funnelpostcode/"
+ "?PostalCode=75008&Country=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/v1/funnelpostcode/"
+
"?PostalCode=75008&Country=FRA&Licence={LICENCE_CODE}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/v1/funnelpostcode/"
+
"?PostalCode=75008&Country=FRA&Licence={LICENCE_CODE}"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
POSThttps://{SERVER_ADDRESS}/{VERSION}/funnelpostcode/
Senden Sie alle Parameter im Anfrage-Body mit
Content-Type: application/x-www-form-urlencoded.
Die Serveradresse bleibt in der URL.
cURL-Beispiel
curl -X POST "https://{SERVER_ADDRESS}/v1/funnelpostcode/"
\
-H "Content-Type: application/x-www-form-urlencoded"
\
-d "PostalCode=75008" \
-d "Country=FRA" \
-d "Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/funnelpostcode/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
PostalCode: "75008",
Country: "FRA",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/v1/funnelpostcode/",
data={
"PostalCode": "75008",
"Country": "FRA",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funnelpostcode/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'PostalCode' => '75008',
'Country' => 'FRA',
'Licence' => '{LICENCE_CODE}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/v1/funnelpostcode/',
qs.stringify({
PostalCode: '75008',
Country: 'FRA',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "PostalCode=75008&Country=FRA&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/v1/funnelpostcode/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["PostalCode"] = "75008",
["Country"] = "FRA",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/v1/funnelpostcode/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Werts{}
form.Set("PostalCode", "75008")
form.Set("Country", "FRA")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/v1/funnelpostcode/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Parameter
| Parameter | Wert | Beschreibung | Pflicht/Optional |
|---|---|---|---|
| Licence |
{LICENCE_CODE}
|
Ihr DQE-Lizenzschlüssel oder OAuth2-Token. Wenden Sie sich an den Support, falls Sie noch keinen haben. | Pflicht |
| PostalCode |
{POSTAL_CODE}
|
Eingabe der Postleitzahl oder des Ortsnamens. | Pflicht |
| Country |
{COUNTRY_CODE}
|
ISO-3166-1-Alpha-3-Ländercode für den Suchbereich
der Adresse. Beispiel: FRA oder
GBR.
|
Pflicht |
| Extended |
Y or N
|
Ermöglicht die Suche ab nur 2 Zeichen in der
Postleitzahleingabe.
Standard: N.
|
Optional |
| Limit |
{NB}
|
Maximale Anzahl der zurückgegebenen Ortsvorschläge. | Optional |
| Length |
{LENGTH}
|
Maximale Zeichenlänge für zurückgegebene Adressfelder.
Gilt nur für Adressen mit lateinischen Zeichen.
Standard: 38. Empfohlenes
Minimum: 32.
|
Optional |
| Filter |
{FILTER}
|
Steuert die Art der zurückgegebenen Ergebnisse.
Wird
er weggelassen, enthält die Antwort Postleitzahlen,
Straßen (sofern verfügbar) und CEDEX-Einträge.1 = nur Postleitzahl & CEDEX
· 2 = Postleitzahl &
Straße (ohne CEDEX) · 3 = nur
Postleitzahl · 4 = ein Vorschlag
pro Postleitzahl & Ort (nur Malaysia)
|
Optional |
| Langue |
{LANGUAGE}
|
Filtert Ergebnisse nach Sprache/Schriftsystem.
JPN:
JP = Kanji · JK
= Katakana · EN = Romanisiert.
HKG: EN · ZH. THA:
EN · TH. Siehe
Sprachleitfaden.
|
Optional |
Frankreich & Belgien: Postleitzahlen
können mehreren Gemeinden zugeordnet sein (fragmentierte
Gruppierung). funnelpostcode gibt pro Gemeinde eine
Ergebniszeile zurück.
Antwort
Bei Erfolg gibt die API ein JSON-Objekt zurück, das
eine Anzahl Found und ein Array
PostalCodes enthält.
Reihenfolge der Ergebnisse - Die Ergebnisse
werden nach Relevanz gereiht, nicht nach aufsteigender
Postleitzahl. Wird eine exakte Postleitzahl eingegeben,
die einer einzigen Stadt entspricht, wird ein Ergebnis
zurückgegeben. Wird eine unvollständige Postleitzahl mit
Extended=Y eingegeben, werden die Ergebnisse
nach Bevölkerungsdichte sortiert (größte Stadt zuerst).
Wird ein Ortsname eingegeben (vollständig oder teilweise),
erscheinen exakte Treffer zuerst, gefolgt von einer
Relevanzreihung nach Schlüsselwörtern.
Oberste Ebene
| Schlüssel | Beschreibung | Typ |
|---|---|---|
| Found | Anzahl der zurückgegebenen Ortsvorschlagsobjekte. | Integer |
| PostalCodes | Array von Ortsvorschlagsobjekten. | Array |
Ortsvorschlagsobjekt - PostalCodes[n]
| Schlüssel | Beschreibung | Frankreich | International |
|---|---|---|---|
| PostalCode | Postleitzahl der Adresse. | String (10) | String (10) |
| City | Stadtname. | String (38) | String (50) |
| Hamlet | Benannter Ortsteil oder Weiler (Frankreich) bzw. entsprechendes Feld auf Bezirksebene (international). Die Verfügbarkeit variiert je nach Land. | String (38) | String (50) |
| SpecialDistribution |
CEDEX-Indikator: 1 = CEDEX-Adresse,
0 = keine CEDEX-Adresse.
|
String (1) | String (1) |
| Country | ISO-3166-1-Alpha-3-Ländercode. | String (3) | String (3) |
| AdministrativeArea | Landkreis oder entsprechende Verwaltungsebene. | Empty | String (50) |
| StateLabel |
ISO-Bezeichnung des Bundeslands bzw. der Verwaltungsregion
(z. B. ISHIKAWA für Japan).
|
Not available | String (50) |
| StateCode |
ISO-Code des Bundeslands bzw. der Verwaltungsregion
(z. B. 17 für Japan).
|
String (50) | String (50) |
| SubLocality | Unterort (Bezirk, Stadtteil, Vorort). | Empty | String (50) |
| CityId | Eindeutige Stadtkennung (INSEE-Code für Frankreich). | String (20) | String (20) |
| Latitude | Geokoordinaten des gefundenen Orts. Nicht für alle Länder verfügbar - siehe Abdeckung. | String | String |
| Longitude | Geokoordinaten des gefundenen Orts. Nicht für alle Länder verfügbar - siehe Abdeckung. | String | String |
Informations-Objekt - PostalCodes[n].Informations
Wird nur befüllt, wenn die Postleitzahl direkt einer bestimmten Adresse zugeordnet ist (z. B. CEDEX-Codes in Frankreich). Andernfalls sind alle Felder leer.
| Schlüssel | Beschreibung | Frankreich | International |
|---|---|---|---|
| AdditionalAddress | Zusätzliche Adresszeile. | Empty | String (50) |
| AdditionalAddress_2 | Zweite zusätzliche Adresszeile. | Empty | String (50) |
| StreetNumberList |
Durch Semikolon getrennte Liste gültiger Hausnummern
für die gefundene Straße. Enthält immer
alle Nummern, wenn vorhanden; leer, wenn StreetId
fehlt.
|
String (1024) | String (1024) |
| StreetType |
Straßentyp (z. B. RUE, AVENUE,
BOULEVARD). Wird nicht für alle
internationalen Datensätze zurückgegeben.
|
String (20) | String (20) |
| Street | Straßenname. | String (38) | String (150) |
| Suburb | Vorort oder Stadtteil. | Empty | String (50) |
| StreetId |
Eindeutige Straßenkennung. Wird nur befüllt,
wenn
die Postleitzahl einer bestimmten Straße zugeordnet
ist. Ist sie vorhanden, können Sie funneladdress
überspringen und StreetId direkt
an
funnelcompl übergeben.
|
String (20) | String (20) |
| Company | Firmenname. | String (38) | String (38) |
Antwort example
Antwortbeispiel - Frankreich (75008 Paris)
{
"Found": 1,
"PostalCodes": [
{
"PostalCode":
"75008",
"City":
"PARIS",
"Hamlet":
"",
"SpecialDistribution":
"0",
"Country":
"FRA",
"AdministrativeArea":
"",
"StateLabel":
"",
"StateCode":
"*",
"SubLocality":
"",
"CityId":
"75108",
"Latitude":
"48.8775112171854",
"Longitude":
"2.31760169076841",
"Informations": {
"AdditionalAddress":
"",
"AdditionalAddress_2":
"",
"StreetNumberList":
"",
"StreetType":
"",
"Street":
"",
"Suburb":
"",
"StreetId":
"",
"Company":
""
}
}
]
}
Antwortbeispiel - Japan (108-6390)
{
"Found": 3,
"PostalCodes": [
{
"PostalCode":
"108-6390",
"City":
"ﾐﾅﾄｸ",
"Hamlet":
"",
"SpecialDistribution":
"0",
"Country":
"JPN",
"AdministrativeArea":
"ﾐﾅﾄｸ",
"StateLabel":
"ﾄｳｷﾖｳﾄ",
"StateCode":
"13",
"SubLocality":
"",
"CityId":
"402574_1086390",
"Latitude":
"",
"Longitude":
"",
"Informations": {
"AdditionalAddress":
"",
"AdditionalAddress_2":
"",
"StreetNumberList":
"",
"StreetType":
"",
"Street":
"",
"Suburb":
"",
"StreetId":
"",
"Company":
""
}
}
]
}
Fehler
Der RESTful-Endpunkt gibt einen strukturierten JSON-Fehlerkörper mit einem HTTP-Statuscode, einer Meldung und einer Fehlerkennung zurück.
| HTTP | Fehlertyp | Antworttext |
|---|---|---|
| 400 | Fehlender Pflichtparameter |
{"status":400,"message":"Missing parameters","details":"PostalCode,Licence","error":"bad
request"}
|
| 400 | Ländercode ist kein gültiger ISO-3166-1-Alpha-3-Code |
{"status":400,"message":"Country doesn't
exist","details":"INVALID","error":"bad
request"}
details gibt den Wert zurück,
den Sie
in Country gesendet haben -
es
zeigt Ihre tatsächliche Eingabe, nicht immer
den hier gezeigten Literalwert
INVALID.
|
| 401 | Falsche oder nicht autorisierte Lizenznummer |
{"status":401,"message":"Your licence
is not allowed to cover this functionnality","details":"WRONG","error":"unauthorized_client"}
|
API testen
Klicken Sie auf die Schaltfläche unten, um diesen Endpunkt live in Ihrem Browser zu testen.
Konsole öffnen
Adresssuche (funneladdress)
Zweiter Schritt des Trichter-Ansatzes. Anhand eines
CityId von funnelpostcode und eines teilweisen
Straßennamens werden passende Straßen zurückgegeben.
Das Feld StreetId aus jedem Ergebnis dient
als Eingabe für den letzten Schritt: funnelcompl.
Anfrage
funneladdress unterstützt sowohl GET als auch POST.
{SERVER_ADDRESS}, {VERSION}
und {LICENCE_CODE} werden von DQE bei
der Kontoerstellung bereitgestellt. {CITY_ID}
stammt aus der funnelpostcode-Antwort, wenn der Nutzer
eine Stadt auswählt. Wenden Sie sich an Ihren
DQE-Kundenbetreuer, um diese Zugangsdaten zu erhalten.
Die Adresseingabe muss URL-codiert sein - z. B.
l'église
→ l%27%C3%A9glise.
GEThttps://{SERVER_ADDRESS}/{VERSION}/funneladdress/?CityId={CITY_ID}&Country={COUNTRY_CODE}&Street={INPUT}&Licence={LICENCE_CODE}
cURL-Beispiel
Frankreich - CityId aus dem vorherigen funnelpostcode-Schritt
curl "https://{SERVER_ADDRESS}/v1/funneladdress/?CityId=75108&Country=FRA&Street=bienfaisance&Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/funneladdress/?"
+ new URLSearchParams({
CityId: "75108",
Country: "FRA",
Street: "bienfaisance",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/v1/funneladdress/",
params={
"CityId": "75108",
"Country": "FRA",
"Street": "bienfaisance",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'CityId' => '75108',
'Country' => 'FRA',
'Street' => 'bienfaisance',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funneladdress/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/v1/funneladdress/',
{
params: {
CityId: '75108',
Country: 'FRA',
Street: 'bienfaisance',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/v1/funneladdress/"
+ "?CityId=75108&Country=FRA&Street=bienfaisance&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/v1/funneladdress/"
+
"?CityId=75108&Country=FRA&Street=bienfaisance&Licence={LICENCE_CODE}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/v1/funneladdress/"
+
"?CityId=75108&Country=FRA&Street=bienfaisance&Licence={LICENCE_CODE}"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
POSThttps://{SERVER_ADDRESS}/{VERSION}/funneladdress/
Senden Sie alle Parameter im Anfrage-Body mit
Content-Type: application/x-www-form-urlencoded.
Die Serveradresse bleibt in der URL.
cURL-Beispiel
curl -X POST "https://{SERVER_ADDRESS}/v1/funneladdress/"
\
-H "Content-Type: application/x-www-form-urlencoded"
\
-d "CityId=75108" \
-d "Country=FRA" \
-d "Street=bienfaisance" \
-d "Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/funneladdress/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
CityId: "75108",
Country: "FRA",
Street: "bienfaisance",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/v1/funneladdress/",
data={
"CityId": "75108",
"Country": "FRA",
"Street": "bienfaisance",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funneladdress/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'CityId' => '75108',
'Country' => 'FRA',
'Street' => 'bienfaisance',
'Licence' => '{LICENCE_CODE}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/v1/funneladdress/',
qs.stringify({
CityId: '75108',
Country: 'FRA',
Street: 'bienfaisance',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "CityId=75108&Country=FRA&Street=bienfaisance&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/v1/funneladdress/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["CityId"] = "75108",
["Country"] = "FRA",
["Street"] = "bienfaisance",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/v1/funneladdress/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Werts{}
form.Set("CityId", "75108")
form.Set("Country", "FRA")
form.Set("Street", "bienfaisance")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/v1/funneladdress/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Parameter
| Parameter | Wert | Beschreibung | Pflicht/Optional |
|---|---|---|---|
| Licence |
{LICENCE_CODE}
|
Ihr DQE-Lizenzschlüssel oder OAuth2-Token. Wenden Sie sich an den Support, falls Sie noch keinen haben. | Pflicht |
| CityId |
{CITY_ID}
|
Stadtkennung, die von funnelpostcode im Feld
CityId
zurückgegeben wird. Grenzt die Straßensuche
auf die ausgewählte Stadt ein.
|
Pflicht |
| Country |
{COUNTRY_CODE}
|
ISO-3166-1-Alpha-3-Ländercode für den Suchbereich
der Adresse. Beispiel: FRA oder
GBR.
|
Pflicht |
| Street |
{INPUT}
|
Vom Nutzer eingegebener Teil-Straßenname. | Pflicht |
| Limit |
{NB}
|
Maximale Anzahl der zurückgegebenen Adressvorschläge. | Optional |
| Length |
{LENGTH}
|
Maximale Zeichenlänge für zurückgegebene Adressfelder.
Gilt nur für Adressen mit lateinischen Zeichen.
Standard: 38. Empfohlenes
Minimum: 32.
|
Optional |
| Langue |
{LANGUAGE}
|
Filtert Ergebnisse nach Sprache/Schriftsystem.
JPN:
JP Kanji · JK Katakana
· EN Romanisiert. HKG: EN
· ZH. THA: EN ·
TH. Siehe
Sprachleitfaden.
|
Optional |
| Version |
1.1
|
Bei 1.1 wird das Feld Hamlet
für kleine Orte befüllt. Ohne diesen Wert
erscheinen die Namen kleiner Orte stattdessen
in eckigen Klammern im Feld City.
|
Optional |
Antwort
Bei Erfolg ist die Antwort ein JSON-Objekt mit zwei
Schlüsseln oberster Ebene: Found (Ganzzahl)
und Addresses (Array von Adressvorschlagsobjekten).
Oberste Ebene
| Schlüssel | Beschreibung | Typ |
|---|---|---|
| Found | Anzahl der zurückgegebenen Adressvorschlagsobjekte. | Integer |
| Addresses | Array von Adressvorschlagsobjekten. | Array |
Adressvorschlagsobjekt - Addresses[n]
| Schlüssel | Beschreibung | Frankreich | International |
|---|---|---|---|
| PostalCode | Postleitzahl der Adresse. | String (10) | String (10) |
| City | Stadtname. | String (38) | String (50) |
| Hamlet |
Named locality or hamlet (Frankreich) or equivalent
district-level field (international). Populated
when Version=1.1 is set. Availability
varies by country.
|
String (38) | String (50) |
| SpecialDistribution |
CEDEX-Indikator: 1 = CEDEX-Adresse,
0 = keine CEDEX-Adresse.
|
String (1) | String (1) |
| Country | ISO-3166-1-Alpha-3-Ländercode. | String (3) | String (3) |
| StateCode |
ISO-Code des Bundeslands bzw. der Verwaltungsregion
(z. B. 17 für Japan).
|
Empty | String (50) |
| StateLabel |
ISO-Bezeichnung des Bundeslands bzw. der Verwaltungsregion
(z. B. ISHIKAWA für Japan).
|
Not available | String (50) |
| AdministrativeArea | Landkreis oder entsprechende Verwaltungsebene. | Empty | String (50) |
| SubLocality | Unterort (Bezirk, Stadtteil, Vorort). | Empty | String (50) |
| Suburb | Vorort oder Stadtteil. | Empty | String (50) |
| CityId | Eindeutige Stadtkennung (INSEE-Code für Frankreich). | String (20) | String (20) |
| Input | Normalisierte Form der eingegebenen Straße. Kann sich von der ursprünglichen Eingabe in Groß-/Kleinschreibung oder Formatierung unterscheiden. | String (255) | String (255) |
| Label |
Anzeigefertige Zeichenkette für ein Autovervollständigungs-Dropdown.
Zahlen in [eckigen Klammern]
zeigen an, dass die Nummer in den Referenzdaten
nicht gefunden wurde. Siehe
Feld Label - nur zur Anzeige
für Hinweise zur Verwendung.
Verwenden Sie
Label nur zum Befüllen des Vorschlags-Dropdowns - speichern Sie damit niemals die Adresse.Siehe Integrationsleitfaden →
|
Empty | String (255) |
| Street | Straßenname. | String (38) | String (150) |
| StreetId | Eindeutige Straßenkennung. Wird als Eingabe für funnelcompl verwendet. | String (20) | String (20) |
| StreetType |
Straßentyp (z. B. RUE, AVENUE,
BOULEVARD). Wird nicht für alle
internationalen Datensätze zurückgegeben.
|
String (20) | String (20) |
| StreetNumber | Vollständige Hausnummer einschließlich etwaiger Zusätze (bis, ter usw.). | String (38) | String (38) |
| StreetNumberOnly | Nur die Hausnummer, ohne etwaige Zusätze (bis, ter usw.). | Empty | String (4) |
| StreetNumberList | Durch Semikolon 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) |
| StreetNumberListCount | Wenn die abgefragte Hausnummer nicht gefunden wird oder fehlt, wird die Gesamtzahl der gültigen Hausnummern für diese Straße zurückgegeben. | Empty | String |
| IsValidStreetNumber |
Indikator für die Gültigkeit der Hausnummer.
1,
wenn die Nummer in den Referenzdaten existiert,
sonst 0. Gibt bei manchen internationalen
Adressen eine leere Zeichenkette zurück, wenn
keine Validierung auf Hausnummernebene verfügbar
ist.
|
Not available | Integer |
| AdditionalAddress | Zusätzliche Adressinformationen (Gebäudename, Stockwerk usw.). Die Verfügbarkeit variiert je nach Land - siehe Integrationsleitfaden. | Empty | String (50) |
| Company | Firmenname, der der Adresse zugeordnet ist. | String (38) | String (38) |
| 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
bei Version=1.1
Straße ohne Hausnummer ausgewählt?
Siehe Integrationsleitfaden →
Antwort example
Antwortbeispiel - Frankreich (Rue de la Bienfaisance, 75008 Paris)
{
"Found": 1,
"Addresses": [
{
"PostalCode":
"75008",
"City":
"PARIS",
"Hamlet":
"",
"SpecialDistribution":
"0",
"Country":
"FRA",
"StateCode":
"",
"SubLocality":
"",
"CityId":
"75108",
"Input":
"bienfaisance",
"Label":
"",
"AdditionalAddress":
"",
"StreetNumber":
"",
"StreetType":
"RUE",
"Street":
"RUE DE LA BIENFAISANCE",
"StreetId":
"1454259",
"IsValidStreetNumber":
"",
"StreetNumberListCount":"",
"StreetNumberList":
"1;2;3;3B;4;6;7;7B;8;9;10;12;12B;15;16;17;19;20;21;23;25;26;27;28;29;30;32;33;34;35;36;37;39;40;41;42;43;44;45;46;47;48;50;51;52;52B;54",
"StreetNumberOnly":
"",
"StateLabel":
"",
"AdministrativeArea":
"",
"Suburb":
"",
"Company":
"",
"Latitude":
"48.876526",
"Longitude":
"2.316451" }
]
}
Antwortbeispiel - Japan (三田, 108-6390)
Japan - CityId 402573_1086390, Langue=JP (Kanji)
{
"Found": 1,
"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":
"" }
]
}
Fehler
Der RESTful-Endpunkt gibt einen strukturierten JSON-Fehlerkörper mit einem HTTP-Statuscode, einer Meldung und einer Fehlerkennung zurück.
| HTTP | Fehlertyp | Antworttext |
|---|---|---|
| 400 | Fehlender Pflichtparameter |
{"status":400,"message":"Missing parameters","details":"CityID","error":"bad
request"}
|
| 400 | Ländercode ist kein gültiger ISO-3166-1-Alpha-3-Code |
{"status":400,"message":"Country doesn't
exist","details":"JPNde","error":"bad
request"}
details gibt den Wert zurück,
den Sie
in Country gesendet haben -
es
zeigt Ihre tatsächliche Eingabe, nicht immer
den hier gezeigten Literalwert
JPNde.
|
| 401 | Falsche oder nicht autorisierte Lizenznummer |
{"status":401,"message":"Your licence
is not allowed to cover this functionnality","details":"WRONG
LICENSE","error":"unauthorized_client"}
|
API testen
Klicken Sie auf die Schaltfläche unten, um diesen Endpunkt live in Ihrem Browser zu testen.
Konsole öffnen
Gebäude (funnelcompl)
Letzter Schritt des Trichter-Ansatzes. Anhand von
StreetId und StreetNumber aus
funneladdress wird eine Liste von Gebäudeteil-Vorschlägen
zurückgegeben: Gebäudenamen, Stockwerksnummern, Firmennamen,
Wohnungsnummern.
Anfrage
funnelcompl unterstützt sowohl GET als auch POST.
{SERVER_ADDRESS}, {VERSION}
und {LICENCE_CODE} werden von DQE bei
der Kontoerstellung bereitgestellt. {STREET_ID}
stammt aus dem Feld
StreetId der
funneladdress-Antwort, wenn der Nutzer eine Straße
auswählt. Wenden Sie sich an Ihren DQE-Kundenbetreuer,
um diese Zugangsdaten zu erhalten.
GEThttps://{SERVER_ADDRESS}/{VERSION}/funnelcompl/?StreetId={STREET_ID}&Country={COUNTRY_CODE}&StreetNumber={NUMBER}&Licence={LICENCE_CODE}
cURL-Beispiel
Frankreich - StreetId aus dem vorherigen funneladdress-Schritt
curl "https://{SERVER_ADDRESS}/v1/funnelcompl/?StreetId=2408474&Country=FRA&StreetNumber=1&Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/funnelcompl/?"
+ new URLSearchParams({
StreetId: "2408474",
Country: "FRA",
StreetNumber: "1",
Licence: "{LICENCE_CODE}"
}))
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.get(
"https://{SERVER_ADDRESS}/v1/funnelcompl/",
params={
"StreetId": "2408474",
"Country": "FRA",
"StreetNumber": "1",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$params = http_build_query([
'StreetId' => '2408474',
'Country' => 'FRA',
'StreetNumber' => '1',
'Licence' => '{LICENCE_CODE}',
]);
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funnelcompl/?{$params}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
axios.get('https://{SERVER_ADDRESS}/v1/funnelcompl/',
{
params: {
StreetId: '2408474',
Country: 'FRA',
StreetNumber: '1',
Licence: '{LICENCE_CODE}'
}
})
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String url = "https://{SERVER_ADDRESS}/v1/funnelcompl/"
+ "?StreetId=2408474&Country=FRA&StreetNumber=1&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var url = "https://{SERVER_ADDRESS}/v1/funnelcompl/"
+
"?StreetId=2408474&Country=FRA&StreetNumber=1&Licence={LICENCE_CODE}";
var response = await client.GetAsync(url);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://{SERVER_ADDRESS}/v1/funnelcompl/"
+
"?StreetId=2408474&Country=FRA&StreetNumber=1&Licence={LICENCE_CODE}"
resp, err := http.Get(url)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Wenn der Nutzer keine Hausnummer eingegeben hat,
übergeben Sie einen leeren Parameter StreetNumber:
&StreetNumber=
POSThttps://{SERVER_ADDRESS}/{VERSION}/funnelcompl/
Senden Sie alle Parameter im Anfrage-Body mit
Content-Type: application/x-www-form-urlencoded.
Die Serveradresse bleibt in der URL.
cURL-Beispiel
curl -X POST "https://{SERVER_ADDRESS}/v1/funnelcompl/"
\
-H "Content-Type: application/x-www-form-urlencoded"
\
-d "StreetId=0751080070" \
-d "Country=FRA" \
-d "StreetNumber=17" \
-d "Licence={LICENCE_CODE}"
fetch("https://{SERVER_ADDRESS}/v1/funnelcompl/",
{
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded"
},
body: new URLSearchParams({
StreetId: "0751080070",
Country: "FRA",
StreetNumber: "17",
Licence: "{LICENCE_CODE}"
})
})
.then(r => r.json())
.then(data => console.log(data));
import requests
response = requests.post(
"https://{SERVER_ADDRESS}/v1/funnelcompl/",
data={
"StreetId": "0751080070",
"Country": "FRA",
"StreetNumber": "17",
"Licence": "{LICENCE_CODE}",
},
)
print(response.json())
<?php
$ch = curl_init("https://{SERVER_ADDRESS}/v1/funnelcompl/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
'StreetId' => '0751080070',
'Country' => 'FRA',
'StreetNumber' => '17',
'Licence' => '{LICENCE_CODE}',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER,
true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
const axios = require('axios');
const qs = require('querystring');
axios.post('https://{SERVER_ADDRESS}/v1/funnelcompl/',
qs.stringify({
StreetId: '0751080070',
Country: 'FRA',
StreetNumber: '17',
Licence: '{LICENCE_CODE}'
}))
.then(response => console.log(response.data));
HttpClient client = HttpClient.newHttpClient();
String form = "StreetId=0751080070&Country=FRA&StreetNumber=17&Licence={LICENCE_CODE}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{SERVER_ADDRESS}/v1/funnelcompl/"))
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(form))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
using var client = new HttpClient();
var form = new Dictionary<string, string>
{
["StreetId"] = "0751080070",
["Country"] = "FRA",
["StreetNumber"] = "17",
["Licence"] = "{LICENCE_CODE}"
};
var response = await client.PostAsync(
"https://{SERVER_ADDRESS}/v1/funnelcompl/",
new FormUrlEncodedContent(form));
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
func main() {
form := url.Werts{}
form.Set("StreetId", "0751080070")
form.Set("Country", "FRA")
form.Set("StreetNumber", "17")
form.Set("Licence", "{LICENCE_CODE}")
resp, err := http.PostForm("https://{SERVER_ADDRESS}/v1/funnelcompl/",
form)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Parameter
| Parameter | Wert | Beschreibung | Pflicht/Optional |
|---|---|---|---|
| Licence |
{LICENCE_CODE}
|
Ihr DQE-Lizenzschlüssel oder OAuth2-Token. Wenden Sie sich an den Support, falls Sie noch keinen haben. | Pflicht |
| StreetId |
{STREET_ID}
|
Eindeutige Straßenkennung, die von funneladdress
im
Feld StreetId zurückgegeben wird.
|
Pflicht |
| Country |
{COUNTRY_CODE}
|
ISO-3166-1-Alpha-3-Ländercode für den Suchbereich
der Adresse. Beispiel: FRA oder
GBR.
|
Pflicht |
| StreetNumber |
{NUMBER}
|
Vom Nutzer ausgewählte Hausnummer - entspricht
dem
Feld StreetNumber aus der funneladdress-Antwort.
|
Pflicht |
| Length |
{LENGTH}
|
Maximale Zeichenlänge für zurückgegebene Adressfelder.
Gilt nur für Adressen mit lateinischen Zeichen.
Ein zu niedriger Wert kann Ergebnisse abschneiden.
Standard: 38. Empfohlenes Minimum:
32.
|
Optional |
Antwort
Bei Erfolg ist die Antwort ein JSON-Objekt mit drei
Schlüsseln oberster Ebene: Found,
AdditionalAddresses (Array) und einem
Geokoordinaten-Objekt Geolocalisation.
Fehlende Gebäudeteil-Daten sind kein Fehler.Siehe Integrationsleitfaden →
Oberste Ebene
| Schlüssel | Beschreibung | Typ |
|---|---|---|
| Found | Anzahl der zurückgegebenen Adresszusatzobjekte. | Integer |
| AdditionalAddresses | Array von Adresszusatzobjekten. | Array |
| Geolocalisation | Geokoordinaten der gefundenen Adresse. Leer, wenn für diesen Adresstyp nicht verfügbar. | Object |
AdditionalAddress-Objekt - AdditionalAddresses[n]
| Schlüssel | Beschreibung | Frankreich | International |
|---|---|---|---|
| AdditionalAddress | Bezeichnung des Gebäude- oder Wohnungszusatzes. | String (38) | String (150) |
| PostalCode | Postleitzahl, die dem Gebäudeteil zugeordnet ist. | String | String |
Geokoordinaten - Geolocalisation
| Schlüssel | Beschreibung | Frankreich | International |
|---|---|---|---|
| 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 |
Antwort example
Antwortbeispiel - Frankreich (1 Rue de la Louisiane, 31200 Toulouse)
{
"Found": 4,
"AdditionalAddresses": [
{ "AdditionalAddress":
"BATIMENT A RESIDENCE ALLEE DES CEDRES",
"PostalCode":
"" },
{ "AdditionalAddress":
"BATIMENT B RESIDENCE ALLEE DES CEDRES",
"PostalCode":
"" },
{ "AdditionalAddress":
"BATIMENT C RESIDENCE ALLEE DES CEDRES",
"PostalCode":
"" },
{ "AdditionalAddress":
"BATIMENT D RESIDENCE ALLEE DES CEDRES",
"PostalCode":
"" }
],
"Geolocalisation": {
"Latitude":
"",
"Longitude":
"" }
}
Fehler
Der RESTful-Endpunkt gibt einen strukturierten JSON-Fehlerkörper mit einem HTTP-Statuscode, einer Meldung und einer Fehlerkennung zurück.
| HTTP | Fehlertyp | Antworttext |
|---|---|---|
| 400 | Fehlender Pflichtparameter |
{"status":400,"message":"Missing parameters","details":"StreetId","error":"bad
request"}
|
| 400 | Ländercode ist kein gültiger ISO-3166-1-Alpha-3-Code |
{"status":400,"message":"Country doesn't
exist","details":"JPNde","error":"bad
request"}
details gibt den Wert zurück,
den Sie
in Country gesendet haben -
es
zeigt Ihre tatsächliche Eingabe, nicht immer
den hier gezeigten Literalwert
JPNde.
|
| 401 | Falsche oder nicht autorisierte Lizenznummer |
{"status":401,"message":"Your licence
is not allowed to cover this functionnality","details":"WRONG
LICENSE","error":"unauthorized_client"}
|
API testen
Klicken Sie auf die Schaltfläche unten, um diesen Endpunkt live in Ihrem Browser zu testen.
Konsole öffnen
Siehe auch
Verknüpfung mit