/api/v5/Autocomplete/guidedSearch (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/guidedSearch

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}}

Comparison interfaces

Description /Autocomplete /Autocomplete /guidedSearch
Allows searching a string across all attributes of spatial data such as address data. Attributes are: City, village municipality, district, country, county, administrative region, residential area, state, street, postal code, point of interest.
Allows to exclude any number of types of spatial data that may appear in the results list: Train station, airport, city, village municipality, district, country, county, administrative region, housing estate, state, street, postal code, point of interest.
Allows to specify any number of certain types of spatial data that may appear in the results list: Train station, airport, city, village municipality, district, country, county, administrative region, housing estate, state, street, postal code, point of interest.
Allows you to specify the maximum number of results that will be returned.
Set output of the result list as geoJson or geoEntities.
Allows prioritizing the possible spatial data in a rectangle on the map.
Allows prioritizing the possible spatial data within a radius of a center point.
Allows to limit the result list of spatial data to any number of countries.
Allows to localize the attributes of spatial data of the result list.
Allows to limit the results of spatial data in such a way that a zip code is stored with them.
Allows the restriction that spatial data is of interest in a particular city, village, district, country, county, administrative region, residential area, state, street, zip code, town, or combinations thereof.
Allows searching by a specific attribute of spatial data: city, village municipality, district, country, county, administrative region, housing estate, state, street, postal code, point of interest.
Allows to specify that the return is of the type of spatial data over which is also searched: City, village municipality, district, country, county, administrative region, housing estate, state, street, postal code, point of interest.

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": {
        "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 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. Only the first element will be used. string[]? null
filterOptions.city Filters the result list and makes sure that the passed value corresponds to the value in the result list. Allows restricting the city. string? null
filterOptions.village Filters the result list and makes sure that the passed value corresponds to the value in the result list. Allows restricting the village. string? null
filterOptions.cityPart Filters the result list and makes sure that the passed value corresponds to the value in the result list. Allows restricting the city part. string? null
filterOptions.country Filters the result list and makes sure that the passed value corresponds to the value in the result list. Allows restricting the country. string? null
filterOptions.county Filters the result list and makes sure that the passed value corresponds to the value in the result list. Allows restricting the county. string? null
filterOptions.district Filters the result list and makes sure that the passed value corresponds to the value in the result list. Allows restricting the district. string? null
filterOptions.neighbourhood Filters the result list and makes sure that the passed value corresponds to the value in the result list. Allows restricting the neighbourhood. string? null
filterOptions.state Filters the result list and makes sure that the passed value corresponds to the value in the result list. Allows restricting the state. string? null
filterOptions.street Filters the result list and makes sure that the passed value corresponds to the value in the result list. Allows restricting the street. string? null
filterOptions.zip Filters the result list and makes sure that the passed value corresponds to the value in the result list. Allows restricting the postal code. string? null
filterOptions.poi Filters the result list and makes sure that the passed value corresponds to the value in the result list. Allows restricting the point of interest. string? null
filterOptions.searchField Allows to specify what the passed search string from query should be applied. The following values are allowed: city, village, cityPart, country, county, district, neighbourhood, state, street, zip, searchField, poi. string? null
filterOptions.strictFieldSearch Ensures that the results returned match the type of the field (filterOptions.searchField). 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
locale Specifies the localization with which the strings are filled. e.g.: country, state... string
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/guidedSearch' \
--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