/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

Die Parameter werden im 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": 0
}
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? true
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

Der Rückgabecontainer ist vom Typ geoEntities oder geoJson. Der Zeichensatz ist utf-8.

geoEntities

{
    "geoEntities": [
        {
            "locale": null,
            "geoEntityType": "TRAIN_STATION",
            "country": "Deutschland",
            "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": {
                "Locale": null,
                "GeoEntityType": "TRAIN_STATION",
                "country": "Deutschland",
                "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
locale Gibt die Lokalisierung an, mit denen die Strings gefüllt sind. z. B: country, state... string
geoEntityType Gibt den Typ an, um den es sich handelt: COUNTY, COUNTRY, DISTRICT, NEIGHBOURHOOD, STATE, STREET, STREET_WITHOUT_CITY, TRAIN_STATION, AIRPORT, ZIP string
country Gibt das Land 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

Beachten Sie, dass in dem 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