Autocomplete

Die SmartMaps Autocomplete API stellt Endpunkte für die Durchführung von Autocomplete-Suchen auf geografischen Daten bereit. Sie ermöglicht die Suche nach Städten, Straßen, Points of Interest und anderen räumlichen Entitäten.

Authentifizierung

Bearer-Token erforderlich

Die Autocomplete API akzeptiert Ihren API-Key nicht direkt. Sie müssen Ihren API-Key zunächst gegen ein kurzlebiges Bearer-Token eintauschen und dieses in jeder Anfrage mitsenden.

Authorization: Bearer {{authentication-token}}

Das Token erhalten Sie über:

GET https://www.yellowmap.de/api_rst/api/autocompleteToken?apiKey=[INSERT API-KEY]

Tokens laufen nach 10 Minuten ab — Ihre Anwendung muss vor Ablauf ein neues Token anfordern.

Vollständige Details finden Sie unter Token API. Wenn Sie die manuelle Token-Verwaltung vermeiden möchten, verwenden Sie stattdessen die Autocomplete Library.

Endpunkte

Führt eine Autocomplete-Suche anhand des angegebenen Such-Strings und optionaler Parameter durch.

URL: https://autocomplete.smartmaps.cloud/api/v5/Autocomplete

Methoden: POST

Parameter:

Parameter	Typ	Beschreibung
`query`	string	Der Eingabe-String für die Autocomplete-Anfrage.
`geoJson`	boolean	Legt den Rückgabetyp fest. Bei `true` werden die Daten als GeoJSON zurückgegeben. Bei `false` wird die Ergebnisliste als JSON zurückgegeben. Standard ist `false`.
`boostOptions`	object	Optionen zur Gewichtung der Ergebnisse anhand geografischer Nähe oder einer Bounding Box.
`boostOptions.proximityBoost`	object	Gewichtet die Ergebnisliste anhand einer geografischen Koordinate und eines Radius.
`boostOptions.proximityBoost.radius`	number	Der Radius für den Proximity Boost.
`boostOptions.proximityBoost.value`	number	Der Gewichtungswert für den Proximity Boost.
`boostOptions.boundingBoxBoost`	object	Gewichtet die Ergebnisliste anhand eines Rechtecks.
`boostOptions.boundingBoxBoost.value`	number	Der BoundingBoxBoost gewichtet die Ergebnisliste anhand eines Rechtecks. Das Bounding-Box-Rechteck. Je höher der `value` in boundingBoxBoost, desto stärker werden Ergebnisse im Rechteck bevorzugt. Das Rechteck wird über den Parameter `boundingbox` übergeben (siehe unten).
`boundingbox`	object	Definiert das Bounding-Box-Rechteck für `boostOptions.boundingBoxBoost`.
`boundingbox.leftDown`	object	Die untere linke Ecke der Bounding Box.
`boundingbox.leftDown.latitude`	number	Der Breitengrad der unteren linken Ecke.
`boundingbox.leftDown.longitude`	number	Der Längengrad der unteren linken Ecke.
`boundingbox.rightUp`	object	Die obere rechte Ecke der Bounding Box.
`boundingbox.rightUp.latitude`	number	Der Breitengrad der oberen rechten Ecke.
`boundingbox.rightUp.longitude`	number	Der Längengrad der oberen rechten Ecke.
`center`	object	Definiert die geografische Koordinate für den Mittelpunkt des `boostOptions.proximityBoost`.
`center.latitude`	number	Der Breitengrad des Mittelpunkts.
`center.longitude`	number	Der Längengrad des Mittelpunkts.
`isoCountries`	array	Ein Array von Ländercodes (ISO-3166-2), um die Suche auf bestimmte Länder zu beschränken. Wird nichts angegeben, wird in allen unterstützten Ländern gesucht.
`isoLanguages`	array	Ein Array von Sprachcodes (ISO-639-1), um die zurückzugebenden Lokalisierungen festzulegen. Wird nichts angegeben, werden alle unterstützten Sprachen zurückgegeben.
`filterOptions`	object	Optionen zum Filtern der Ergebnisse.
`filterOptions.plzSearch`	boolean	Bei `true` werden nur Ergebnisse mit einer Postleitzahl zurückgegeben. Standard ist `false`.
`filterOptions.includedGeoEntities`	array	Ein Array räumlicher Datentypen, die in die Ergebnisse einbezogen werden sollen. Unterstützte Typen: `AIRPORT`, `CITY`, `CITY_WITH_ZIP`, `CITYPART`, `CITYPART_WITH_ZIP`, `COUNTY`, `COUNTRY`, `DISTRICT`, `NEIGHBOURHOOD`, `STATE`, `STREET`, `STREET_WITHOUT_CITY`, `TRAIN_STATION`, `ZIP`, `ISLAND`, `VILLAGE`, `ATTRACTION`.
`filterOptions.excludedGeoEntities`	array	Ein Array räumlicher Datentypen, die von den Ergebnissen ausgeschlossen werden sollen. Unterstützte Typen sind dieselben wie bei `includedGeoEntities`.
`filterOptions.inBoundingBox`	boolean	Bei `true` werden nur Ergebnisse innerhalb der angegebenen Bounding Box zurückgegeben. Standard ist `false`.
`top`	integer	Begrenzt die Anzahl der Ergebnisse in der Ergebnisliste. Standard ist `5`.

Antwort:

Die Antwort ist je nach geoJson-Parameter entweder ein geoEntities-Array oder eine GeoJSON-FeatureCollection.

Name	Beschreibung	Datentyp
geoEntityType	Gibt den betreffenden Typ an: 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 den Stadtteil an.	string
district	Gibt den Bezirk an.	string
county	Gibt den Landkreis an.	string
city	Gibt die Stadt an.	string
cityPart	Gibt den Ortsteil an.	string
zip	Gibt die Postleitzahl an.	string
street	Gibt die Straße an.	string
village	Gibt den Ort an.	string
houseNo	Gibt die Hausnummer an.	string
geometry	Gibt einen geografischen Punkt (Längengrad, Breitengrad) an, an dem sich das Element befindet. Dieser kann auf der Karte angezeigt werden, siehe auch die Definition von geoJson.	{}
poi	Gibt den Point of Interest an.	string
osmid	Gibt die osmid des Objekts an.	int
repositoryScore	Zeigt den Score an, der die Relevanz angibt. Je höher, desto relevanter.	double
displayValue	Text, der das Element beschreibt.	string

Beispielantwort

{
    "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,
                "poi": "S Anhalter Bahnhof",
                "_osmid": 0,
                "repositoryScore": 107.5996,
                "displayValue": "S Anhalter Bahnhof, Schöneberger Straße, 10963"
            }
        },
        ...
    ]
}

Fehlerbehandlung

Die API kann die folgenden Fehlercodes zurückgeben:

400 Bad Request: Die Anfrage wurde fehlerhaft gestellt, z. B. aufgrund eines Syntaxfehlers im JSON.
401 Unauthorized: Das Bearer-Token wurde nicht mitgesendet oder ist ungültig.
500 Internal Server Error: Auf der Serverseite ist ein allgemeiner Fehler aufgetreten.

Swagger-Dokumentation

Weitere detaillierte Informationen zu den API-Endpunkten, Parametern und Antwortstrukturen finden Sie in der Swagger-Dokumentation.

Sie können die OpenAPI-Definition (https://autocomplete.smartmaps.cloud/swagger/v1/swagger.json) auch direkt in Postman, Insomnia oder ähnliche API-Clients importieren.