Autocomplete

The SmartMaps Autocomplete API provides endpoints for performing autocomplete searches on geographic data. It allows searching for cities, streets, points of interest, and other spatial entities.

Endpoints

Performs an autocomplete search based on the provided query string and optional parameters.

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

Methods: GET, POST

Parameters:

Parameter	Type	Description
`query`	string	The input string for the autocomplete request.
`geoJson`	boolean	Specifies the return type. If `true`, the data will be returned as GeoJSON. If `false`, the result list is returned as JSON. Default is `false`.
`boostOptions`	object	Options for boosting the results based on geographic proximity or bounding box.
`boostOptions.proximityBoost`	object	Weights the result list according to a geographic coordinate and a radius.
`boostOptions.proximityBoost.radius`	number	The radius for the proximity boost.
`boostOptions.proximityBoost.value`	number	The weight value for the proximity boost.
`boostOptions.boundingBoxBoost`	object	Weights the result list by a rectangle.
`boostOptions.boundingBoxBoost.value`	number	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).
`boundingbox`	object	Defines the bounding box rectangle for the `boostOptions.boundingBoxBoost`.
`boundingbox.leftDown`	object	The lower left corner of the bounding box.
`boundingbox.leftDown.latitude`	number	The latitude of the lower left corner.
`boundingbox.leftDown.longitude`	number	The longitude of the lower left corner.
`boundingbox.rightUp`	object	The upper right corner of the bounding box.
`boundingbox.rightUp.latitude`	number	The latitude of the upper right corner.
`boundingbox.rightUp.longitude`	number	The longitude of the upper right corner.
`center`	object	Defines the geographic coordinate for the center point for the `boostOptions.proximityBoost`.
`center.latitude`	number	The latitude of the center point.
`center.longitude`	number	The longitude of the center point.
`isoCountries`	array	An array of country codes (ISO-3166-2) to limit the search to specific countries. If not provided, all supported countries will be searched.
`isoLanguages`	array	An array of language codes (ISO-639-1) to specify the localizations to be returned. If not provided, all supported languages will be returned.
`filterOptions`	object	Options for filtering the results.
`filterOptions.plzSearch`	boolean	If `true`, only results that have a postal code will be returned. Default is `false`.
`filterOptions.includedGeoEntities`	array	An array of spatial data types to include in the results. Supported types: `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	An array of spatial data types to exclude from the results. Supported types are the same as `includedGeoEntities`.
`filterOptions.inboundingboxS`	boolean	If `true`, only results within the specified bounding box will be returned. Default is `false`.
`top`	integer	Limits the number of results in the result list. Default is `5`.

Response:

The response is either a geoEntities array or a GeoJSON FeatureCollection, depending on the geoJson parameter.

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

Response Example

{
    "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"
            }
        },
        ...
    ]
}

Authentication

The SmartMaps Autocomplete API requires authentication using a bearer token. The token must be included in the Authorization header of the request.

Authorization: Bearer {{authentication-token}}

The authentication token can be obtained from the /api/v5/Autocomplete/authtoken-autocomplete endpoint.

Error Handling

The API may return the following error codes:

400 Bad Request: The request was made incorrectly, e.g., due to a syntax error in the JSON.
401 Unauthorized: The bearer token was not provided or is invalid.
500 Internal Server Error: A general error occurred on the server side.

Swagger Documentation

For more detailed information about the API endpoints, parameters, and response structures, please refer to the Swagger documentation.