/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
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
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
{{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
|