/api/v5/Autocomplete (POST)

  Backend-Service

The backend services are independent services. This is an enterprise function of the SmartMaps. The functionality is not available in SmartMaps FREE. For the activation of a service and further questions we are at your disposal in our support area .


Navigation

Ressource  Path

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

Description

This interface answers an autocomplete request.

To use autocomplete, you must first generate an authentication token. With this interface you get the token:
authtoken-autocomplete

Note that a token is only valid for 10 minutes and must be requested again afterwards.

The authentication token is passed as a bearer token. The bearer token is embedded in the request as an authorization header.

Authorization: Bearer {{authentication-token}}

Parameter

The parameters are included in the body, of the POST request as JSON.
{
    "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": {
        "includedGeoEntities": [
            "string"
        ],
        "excludedGeoEntities": [
            "string"
        ],
        "plzSearch": true,
        "inBoundingBox": true
    },
    "top": 0
}
Name Description Data type Default value
query The input string of the autocomplete request. There is no need to add AND and OR. The separator is the space character. The interpretation of the input is done in the backend of SmartMaps. string? null
geoJson Specifies the return type: If true the data will be returned as GeoJSON. If false the result list is returned as JSON. boolean? false
boostOptions.proximityBoost.radius The proximityBoost weights the result list according to a geographic coordinate and a radius (radius). The higher the value in the proximity boost, the more results in the radius are preferred. The geographic coordinate is passed with the center parameter (see below). double? null
boostOptions.proximityBoost.value double? null
boostOptions.boundingboxBoost.value The BoundingBoxBoost weights the result list by a rectangle. The bounding box rectangle. The higher the value in boundingBoxBoost, the more results in the rectangle are preferred. The rectangle is passed with the boundingbox parameter (see below). double? null
boundingbox.leftDown.latitude Defines the upper right corner (rightUp) and the lower left corner (leftDown) of the rectangle used for the boostOptions.boundingboxBoost. The corner positions are each given as longitude and latitude. double? null
boundingbox.leftDown.longitude double? null
boundingbox.rightUp.latitude double? null
boundingbox.rightUp.longitude double? null
center.latitude Defines the geographic coordinate for the center point for the boostOptions.proximityBoost. The Center is given as longitude and latitude. double? null
center.longitude double? null
isoCountries The countries in which to search: An array with any number of country codes according to ISO-3166-2 is passed. If the parameter is not passed, all supported countries will be searched. string[]? null
isoLanguages Defines the localizations to be returned: An array with any number of country codes according to ISO-3166-2 is passed. If the parameter is not passed, all supported countries will be searched. string[]? null
filterOptions.plzSearch Ensures that only results that have a zip code are returned. boolean? false;
filterOptions.includedGeoEntities Filters the result list so that only entities passed in the array appear in the result list. The following entities are supported: 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 Filters the result list so that only entities that have been passed in the array do not appear in the result list. The following entities are supported: 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 Ensures that only results are displayed that are in the boundingbox. boolean? false;
top Limits the number of results in the result list with the passed value. int? 5

Return

The return container is of type geoEntities or geoJson. The encoding is 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"
            }
        },
        ...
    ]
}

Property names

Name Description Data type
geoEntityType Indicates the type that is involved: COUNTY, COUNTRY, DISTRICT, NEIGHBOURHOOD, STATE, STREET, STREET_WITHOUT_CITY, TRAIN_STATION, AIRPORT, ZIP string
countryLongName Specifies the country. string
country Specifies the country as a alpha-2 code. string
state Specifies the state.. string
neighbourhood Specifies the neighbourhood. string
district Specifies the district. string
county Specifies the county. string
city Specifies the city. string
cityPart Specifies the citypart. string
zip Specifies the postal code. string
street Specifies the street. string
village Specifies the village. string
houseNo Specifies the housenumber. string
geometry Specifies a geographic point (longitude, latitude) where the element is located. This can be displayed on the map, see also definition of geoJson. {}
poi Specifies the point of interest. string
osmid Specifies the osmid from the object. int
repositoryScore Shows the score indicating the relevance. The higher, the more relevant. double
displayValue Text that describes the element. string

Example

Note that in the example the {{Authentication token}} must be set.
curl --location --request POST 'https://autocomplete.smartmaps.cloud/api/v5/Autocomplete' \
--header 'Authorization: Bearer {{authentication-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"
    ]
}'

Error

HTTP-Statuscode Description
400
BAD REQUEST, the request was made incorrectly, e.g.: due to syntax error in the JSON
401
The bearer token was not handed over.
500
General error: e.g.: wrong bearer token