/api/v5/Autocomplete/guidedSearch (POST)
Backend-Service
Die Backend-Services sind eigenständige Services. Hierbei handelt es sich um eine Enterprise-Funktion der SmartMaps. Die Funktionalität ist in SmartMaps FREE nicht verfügbar. Für die Freischaltung eines Dienstes und weiteren Fragen stehen wir Ihnen gerne in unserem Supportbereich zur Verfügung.
Navigation
Ressourcen-Pfad
https://autocomplete.smartmaps.cloud/api/v5/Autocomplete/guidedSearch
Beschreibung
Diese Schnittstelle beantwortet eine Autocomplete-Anfrage.
Um die Autovervollständigung benutzen zu können, muss zuerst ein Authentifizierungstoken generiert werden. Mit dieser Schnittstelle erhalten Sie den Token: authtoken-autocomplete
Beachten Sie, dass ein Token nur 10 Minuten gültig ist und danach neu angefordert werden muss.
Der Authentifizierungstoken wird als Bearer Token übergeben. Das Bearer Token wird als Autorisation Header in die Anfrage eingebettet.
Authorization: Bearer {{Authentifizierungs-Token}}
Vergleich Schnittstellen
Beschreibung | /Autocomplete | /Autocomplete /guidedSearch |
---|---|---|
Erlaubt das Suchen eines Strings über alle Attribute von räumlichen Daten wie z. B. Adressdaten hinweg. Attribute sind: Stadt, Dorfgemeinde, Stadtteil, Land, Landkreis, Verwaltungsregion, Wohnsiedlung, Bundesland, Straße, Postleitzahl, Ort von Interesse. | ✔ | ✔ |
Erlaubt das Ausschließen einer beliebigen Anzahl von Typen von räumlichen Daten, die in der Ergebnisliste vorkommen dürfen: Bahnhof, Flughafen, Stadt, Dorfgemeinde, Stadtteil, Land, Landkreis, Verwaltungsregion, Wohnsiedlung, Bundesland, Straße, Postleitzahl, Ort von Interesse. | ✔ | ✔ |
Erlaubt das Festlegen einer belieben Anzahl bestimmter Typen von räumlichen Daten, die in der Ergebnisliste vorkommen dürfen: Bahnhof, Flughafen, Stadt, Dorfgemeinde, Stadtteil, Land, Landkreis, Verwaltungsregion, Wohnsiedlung, Bundesland, Straße, Postleitzahl, Ort von Interesse. | ✔ | ✔ |
Erlaubt das Festlegen, wie viele Ergebnisse maximal zurückgegeben werden. | ✔ | ✔ |
Ausgabe der Ergebnisliste als geoJson oder geoEntities. | ✔ | ✔ |
Erlaubt das Priorisieren der möglichen räumlichen Daten in einem Rechteck auf der Karte. | ✔ | ✔ |
Erlaubt das Priorisieren der möglichen räumlichen Daten in einem Radius von einem Mittelpunkt. | ✔ | ✔ |
Erlaubt das Einschränken der Ergebnisliste von räumlichen Daten auf eine beliebige Anzahl von Ländern. | ✔ | ✔ |
Erlaubt die Lokalisierung der Attribute von räumlichen Daten der Ergebnisliste. | ✔ | ✔ |
Erlaubt, die Ergebnisse von räumlichen Daten so einzugrenzen, dass bei diesen eine PLZ hinterlegt ist. | ✔ | ✘ |
Erlaubt die Einschränkung, dass räumliche Daten in einer bestimmten Stadt, Dorfgemeinde, Stadtteil, Land, Landkreis, Verwaltungsregion, Wohnsiedlung, Bundesland, Straße, Postleitzahl, Ort von Interesse sind oder Kombinationen davon. | ✘ | ✔ |
Erlaubt die Suche über ein bestimmtes Attribut von räumlichen Daten: Stadt, Dorfgemeinde, Stadtteil, Land, Landkreis, Verwaltungsregion, Wohnsiedlung, Bundesland, Straße, Postleitzahl, Ort von Interesse. | ✘ | ✔ |
Erlaubt das Festlegen, dass die Rückgabe von dem Typ von räumlichen Daten ist, über dem auch gesucht wird: Stadt, Dorfgemeinde, Stadtteil, Land, Landkreis, Verwaltungsregion, Wohnsiedlung, Bundesland, Straße, Postleitzahl, Ort von Interesse. | ✘ | ✔ |
Parameter
body
, des POST-Request als JSON mitgeschickt.{
"query": "string",
"geoJson": true,
"boostOptions": {
"proximityBoost": {
"radius": 0,
"value": 0
},
"boundingBoxBoost": {
"value": 0
}
},
"boundingbox": {
"leftDown": {
"latitude": 0,
"longitude": 0
},
"rightUp": {
"latitude": 0,
"longitude": 0
}
},
"center": {
"latitude": 0,
"longitude": 0
},
"isoCountries": [
"string"
],
"isoLanguages": [
"string"
],
"filterOptions": {
"city": "string",
"village": "string",
"cityPart": "string",
"country": "string",
"county": "string",
"district": "string",
"neighbourhood": "string",
"state": "string",
"street": "string",
"zip": "string",
"searchField": "string",
"poi": "string",
"strictFieldSearch": true,
"includedGeoEntities": [
"string"
],
"excludedGeoEntities": [
"string"
],
"inBoundingBox": true
},
"top": 10
}
Name | Beschreibung | Datentyp | Standardwert |
---|---|---|---|
query |
Die Eingabezeichenfolge des Nutzers. Es muss kein AND und OR hinzugefügt werden. Trennzeichen ist das Leerzeichen. Die Interpretation der Eingabe erfolgt im Backend von SmartMaps. | string? |
null |
geoJson |
Gibt den Rückgabetyp an: Wenn true werden die Daten als GeoJSON zurückgegeben. Wenn false wird die Ergebnisliste als JSON zurückgegeben | boolean? |
false |
boostOptions.proximityBoost.radius |
Der proximityBoost gewichtet die Ergebnisliste nach einer geografischen Koordinate und einem Radius (radius ). Je höher der Wert value im Proximity-Boost ist, je mehr werden Ergebnisse im Radius bevorzugt. Die geografische Koordinate wird mit dem Parameter center (siehe unten) übergeben. |
double? |
null |
boostOptions.proximityBoost.value |
double? |
null | |
boostOptions.boundingboxBoost.value |
Der BoundingBoxBoost gewichtet die Ergebnisliste durch ein Rechteck. Das Begrenzungsrechteck. Je höher der Wert value in boundingBoxBoost ist, je mehr werden Ergebnisse im Rechteck bevorzugt. Das Rechteck wird mit dem Parameter boundingbox (siehe unten) übergeben. |
double? |
null |
boundingbox.leftDown.latitude |
Definiert die obere rechte Ecke (rightUp ) und die linke untere Ecke (leftDown ) des Rechtecks, das für den boostOptions.boundingboxBoost verwendet wird. Die Eckenpositionen werden jeweils als Längen- und Breitengrad (longitude , latitude ) angegeben. |
double? |
null |
boundingbox.leftDown.longitude |
double? |
null | |
boundingbox.rightUp.latitude |
double? |
null | |
boundingbox.rightUp.longitude |
double? |
null | |
center.latitude |
Definiert die geographische Koordinate für den Mittelpunkt für den boostOptions.proximityBoost . Der Mittelpunkt wird jeweils als Längen- und Breitengrad (longitude , latitude ) angegeben. |
double? |
null |
center.longitude |
double? |
null | |
isoCountries |
Die Länder, in denen gesucht werden soll: Es wird ein Array mit beliebig vielen Ländercodes nach ISO-3166-2 übergeben. Wird der Parameter nicht übergeben, wird in allen unterstützten Ländern gesucht. | string[]? |
null |
isoLanguages |
Definiert die Lokalisierungen, die zurückgeben werden soll: Es wird ein Array mit beliebig vielen Ländercodes nach ISO-3166-2 übergeben. | string[]? |
null |
filterOptions.city |
Filtert die Ergebnisliste und stellt sicher, dass der übergebene Wert, dem in der Ergebnisliste entspricht. Erlaubt das Einschränken der Stadt. | string? |
null |
filterOptions.village |
Filtert die Ergebnisliste und stellt sicher, dass der übergebene Wert, dem in der Ergebnisliste entspricht. Erlaubt das Einschränken der Dorfgemeinde. | string? |
null |
filterOptions.cityPart |
Filtert die Ergebnisliste und stellt sicher, dass der übergebene Wert, dem in der Ergebnisliste entspricht. Erlaubt das Einschränken des Stadtteils. | string? |
null |
filterOptions.country |
Filtert die Ergebnisliste und stellt sicher, dass der übergebene Wert, dem in der Ergebnisliste entspricht. Erlaubt das Einschränken des Ländernamens. | string? |
null |
filterOptions.county |
Filtert die Ergebnisliste und stellt sicher, dass der übergebene Wert, dem in der Ergebnisliste entspricht. Erlaubt das Einschränken des Landkreis. | string? |
null |
filterOptions.district |
Filtert die Ergebnisliste und stellt sicher, dass der übergebene Wert, dem in der Ergebnisliste entspricht. Erlaubt das Einschränken der Verwaltungsregion. | string? |
null |
filterOptions.neighbourhood |
Filtert die Ergebnisliste und stellt sicher, dass der übergebene Wert, dem in der Ergebnisliste entspricht. Erlaubt das Einschränken der Wohnsiedlung. | string? |
null |
filterOptions.state |
Filtert die Ergebnisliste und stellt sicher, dass der übergebene Wert, dem in der Ergebnisliste entspricht. Erlaubt das Einschränken des Bundeslands. | string? |
null |
filterOptions.street |
Filtert die Ergebnisliste und stellt sicher, dass der übergebene Wert, dem in der Ergebnisliste entspricht. Erlaubt das Einschränken der Straße. | string? |
null |
filterOptions.zip |
Filtert die Ergebnisliste und stellt sicher, dass der übergebene Wert, dem in der Ergebnisliste entspricht. Erlaubt das Einschränken der Postleitzahl. | string? |
null |
filterOptions.poi |
Filtert die Ergebnisliste und stellt sicher, dass der übergebene Wert, dem in der Ergebnisliste entspricht. Erlaubt das Einschränken des Ortes von Interesse. | string? |
null |
filterOptions.searchField |
Erlaubt das Festlegen, worauf der übergebene Suchstring aus query angewendet werden soll. Erlaubt sind folgende Werte: city, village, cityPart, country, county, district, neighbourhood, state, street, zip, searchField, poi. |
string? |
null |
filterOptions.strictFieldSearch |
Stellt sicher, dass die Ergebnisse, die zurückgeliefert werden, dem Typ des Feldes (filterOptions.searchField ) auf dem gesucht wird, entspricht. |
boolean? |
false |
filterOptions.includedGeoEntities |
Filtert die Ergebnisliste so, dass nur Entitäten, die in dem Array übergeben worden sind, auch in der Ergebnisliste vorkommen. Unterstützt werden folgende Entitäten: UNDEFINED, AIRPORT, CITY, CITY_WITH_ZIP, CITYPART, CITYPART_WITH_ZIP, COUNTY, COUNTRY, DISTRICT, NEIGHBOURHOOD, STATE, STREET, STREET_WITHOUT_CITY, TRAIN_STATION, ZIP, ISLAND, VILLAGE, ATTRACTION. | string[]? |
null |
filterOptions.excludedGeoEntities |
Filtert die Ergebnisliste so, dass nur Entitäten, die in dem Array übergeben worden sind, nicht in der Ergebnisliste vorkommen. Unterstützt werden folgende Entitäten: UNDEFINED, AIRPORT, CITY, CITY_WITH_ZIP, CITYPART, CITYPART_WITH_ZIP, COUNTY, COUNTRY, DISTRICT, NEIGHBOURHOOD, STATE, STREET, STREET_WITHOUT_CITY, TRAIN_STATION, ZIP, ISLAND, VILLAGE, ATTRACTION | string[]? |
null |
filterOptions.inboundingboxS |
Stellt sicher, dass nur Ergebnisse angezeigt werden, die sich in der boundingbox befinden. |
boolean? |
false; |
top |
Beschränkt die Anzahl der Ergebnisse in der Ergebnisliste mit dem übergeben Wert. | int? |
5 |
Rückgabe
geoEntities
oder geoJson
. Der Zeichensatz ist utf-8.geoEntities
{
"geoEntities": [
{
"geoEntityType": "TRAIN_STATION",
"countryLongName": "Deutschland",
"country": "DE",
"state": "Berlin",
"neighbourhood": null,
"district": null,
"county": null,
"city": "Berlin",
"cityPart": "Wilmersdorf",
"zip": "10715",
"street": "Berliner Straße",
"village": null,
"houseNo": null,
"geometry": {
"type": "Point",
"coordinates": [
13.3310103,
52.4873298
]
},
"poi": "U Berliner Straße",
"osmid": 0,
"repositoryScore": 9.306672,
"displayValue": "U Berliner Straße, Berliner Straße, 10715"
},
...
]
}
geoJson
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
13.3814763,
52.5035788
]
},
"properties": {
"GeoEntityType": "TRAIN_STATION",
"countryLongName": "Deutschland",
"country": "DE",
"state": "Berlin",
"neighbourhood": null,
"district": null,
"county": null,
"city": "Berlin",
"cityPart": "Kreuzberg",
"zip": "10963",
"street": "Schöneberger Straße",
"village": null,
"houseNo": null,
"Geometry": {
"Type": "Point",
"Coordinates": [
13.3814763,
52.5035788
]
},
"poi": "S Anhalter Bahnhof",
"_osmid": 0,
"RepositoryScore": 107.5996,
"DisplayValue": "S Anhalter Bahnhof, Schöneberger Straße, 10963"
}
},
...
]
}
Eigenschaftsnamen
Name | Beschreibung | Datentyp |
---|---|---|
geoEntityType |
Gibt den Typ an, um den es sich handelt: COUNTY, COUNTRY, DISTRICT, NEIGHBOURHOOD, STATE, STREET, STREET_WITHOUT_CITY, TRAIN_STATION, AIRPORT, ZIP | string |
countryLongName |
Gibt das Land an. | string |
country |
Gibt das Land als Alpha-2 Code an. | string |
state |
Gibt das Bundesland an. | string |
neighbourhood |
Gibt die Wohnsiedlung an. | string |
district |
Gibt das Verwaltungsregion an. | string |
county |
Gibt den Landkreis an. | string |
city |
Gibt die Stadt an. | string |
cityPart |
Gibt den Stadtteil an. | string |
zip |
Gibt die Postleitzahl an. | string |
street |
Gibt die Straße an. | string |
village |
Gibt die Dorfgemeinde an. | string |
houseNo |
Gibt die Hausnummer an. | string |
geometry |
Gibt einen geografischen Punkt (Längen- und Breitengrad) an, wo sich das Element befindet (Längen-, Breitengrad). Dieser kann auf der Karte darstellt werden, siehe auch Definition von geoJson. | {} |
poi |
Gibt den Ort von Interesse an. | string |
osmid |
Gibt vom Objekt die osmid an. | int |
repositoryScore |
Zeigt den Score, der die Relevanz angibt. Umso höher, umso relevanter. | double |
displayValue |
Text, der das Element beschreibt. | string |
Beispiel
{{Authentifizierungs-Token}}
gesetzt werden muss.curl --location --request POST 'https://autocomplete.smartmaps.cloud/api/v5/Autocomplete/guidedSearch' \
--header 'Authorization: Bearer {{Authentifizierungs-Token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"query": "Berlin",
"geoJson": true,
"boostOptions": {
"proximityBoost": {
"radius": 1000,
"value": 1
}
},
"boundingbox": {},
"center": {
"latitude": 49.000911152000754,
"longitude": 8.41707229614258
},
"isoCountries": [
"de"
]
}'
Fehler
HTTP-Statuscode | Beschreibung |
---|---|
400 |
BAD REQUEST, die Anfrage wurde falsch gestellt, z. B: Durch Syntaxfehler in der JSON
|
401 |
Der Bearer-Token wurde nicht übergeben.
|
500 |
Allgemeiner Fehler: z. B: falscher Bearer-Token
|