Places (Search) API Developer's Guide

Autosuggest Entrypoint

The Autosuggest Entrypoint represents lists of suggested search terms, instants results and refined search links related to a given (partial) search term and location context. This entrypoint is used to help users save time, iterate on their searches, and get the results.

As-you-type-suggestion features of Autosuggest:

auto-suggest - exploratory search queries
disambiguation - providing end-user with contextual information to refine search
instant results of POI and addresses
follow link (href) in instant results and refine search results
highlighted result title text based on what the user typed in

The Autosuggest Entrypoint is a Places (Search) API Core entrypoint.

Entrypoint URI

/autosuggest

Entrypoint Parameters

Parameter	Type	Description
at	Position (format: `latitude,longitude[;cgen=(map\|gps\|sgps)][;u=\d+]`); required, unless one of the Geolocation or X-Map-Viewport headers or the `in` are set. Note: [;cgen=(map\|gps\|sgps)][;u=\d+] is DEPRECATED	Coordinates of search location expressed as latitude, longitude. Additional parameters can be passed which provide more context such as the uncertainty and how the coordinates were generated. For example, "52.5304417,13.4111201", "52.5304417,13.4111201;cgen=gps;u=100" or "52.5304417,13.4111201;u=100". For a full description, see the Location Contexts documentation.
q	String; required	Plain-text search term. For example, "restaurant" or "Brandenburger Tor"
in	Area; required, unless one of the Geolocation or X-Map-Viewport headers or the `at` parameter are set.	This parameter limits results to the boundary of the specified area. The search area can be expressed as: `circle` specified as a centre point with latitude and longitude; and a radius around that point. Format: latitude,longitude;r=\\d+(\\.\\d+)?[;cgen=(map\|gps\|sgps)][;u=\\d+] `bounding box` specified as 4 values, denoting west longitude, south latitude, east longitude, north latitude. For a full description, see the Location Contexts documentation.
route	Route (format: `\[start(latitude,longitude\|[width])\|0..n(latitude,longitude\|[width])\|end(latitude,longitude[width])\][;w=\d+]`); required	This parameter limits search results to the boundary of an area around a route. A route consists of a start coordinate, 0..n turning coordinates and an end coordinate. An optional width in meters can be passed to provide off the route max distance in meters, default: 1000m The points should describe the geometric shape of the route with high precision. Especially, it’s usually not sufficient to only pass maneuvre points as they would be shown to the driver. `width` specifier is `CW` or `HW`. It can follow any of the points to specify whether a route segment is located in a city or on a highway respectively, where segment is the point preceding specifier and following points till the next specifier. This will modify the search distance and possibly algorithm for the segment. `DW` will reset to default width (specified by `w=\d+` ) and algorithm. There are practical limitations to URL lengths. Thus, route parameters with more than 4700 characters will be rejected. A way to reduce this parameter's length is to use a more space-efficient HERE polyline encoding and supply that as the compressedRoute parameter.
compressedRoute	HereEncodedRoute (format: `[a-zA-Z0-9._-]+(;w=\d+)?`); required	This parameter is the new preferred way to specify a route. It contains the coordinates in HERE polyline encoding, which is basically a URL-safe version of Google's polyline encoding format. Additionally, it may contain width attributes for individual parts of the route, i.e. one specify segments to have city width (.C), highway width (.H), or default width (.D). By supplying the suffix ';w=\d+', one can define the actual width of the default width segments in meters.
result_types	Comma-separated list of result type strings; optional	A comma-separated list of the autosuggest result types that should be included in the response. Possible values are: address, place, category, chain. If this parameter is not set, all autosuggest types are considered for the response.
hlStart	String; optional	The delimiter that should be placed before each matched token in the autosuggest response. It defaults to`</b>`. The delimiters are included in the 'highlightedTitle' and 'highlightedVicinity' fields.
hlEnd	String; optional	The delimiter that should be placed after each matched token in the autosuggest response. It defaults to `</b>`. The delimiters are included in the 'highlightedTitle' and 'highlightedVicinity' fields.
cs	Comma-separated list; optional	A comma-separated ordered list of category systems defining which type of category systems should be returned in the response. Valid category systems are 'places', 'cuisines', and 'pds'. Autosuggest currently only supports specifying a single category system per request.
addressFilter	String; optional	Defines constraints used to filter results based on their address. Its value is a semicolon-separated list of key-value pairs. Each value can contain multiple options separated by a comma. Key and value are separated by the equals sign. KeyValuePairType := [Key]=[Value] Supported keys: countryCode (ISO 3166-1-alpha-3), stateCode, county, district, city, zipCode Example: city=berlin,potsdam
recd (DEPRECATED)	Boolean; optional; default: true.	For some endpoints, queries that describe recentering can be used. For example, if the search query is "Restaurants in München", then a recenter is inferred, and the implied search center is München. When this happens, a special result precedes the rest of the result items and describes the fact that a new search center was detected. This parameter determines how distances to the returned results are reported. When the "recd" parameter is set to true, distances returned in the search results are calculated from the detected search center. When false, the distances are reported from the provided search center only. This parameter does not affect search results in any other way. Supported values are: `false` `true`
urgency (DEPRECATED)	Double; optional; default: 1.0.	This parameter is useful when search of interesting places along the route is performed and `route` parameter is specified. There are two different ways of calculating distance along a route. The first way is to compute distance from where you are, along the route, and then perpendicular to the route. The second is to compute distance as the amount of extra travel needed to include the point in the route. The "urgency" parameter allows you to choose between the two, or choose a blending of the two. A value of 1.0 selects for distance along the route, and a value of 0.0 selects the amount of extra travel needed. Values in between weight each method correspondingly.

GET Method

The GET method returns the list of suggested queries, places and address as well as query completions related to the partial search term.

The method allows applications to provide to application users query completion suggestions as they type.

Representation Modifiers

The following options are available in this context:

Parameter	Type	Description
size	Number (non-negative integer); optional	The maximum number of result items in each collection.
tf	String; optional; default: html.	Text format. Determines how rich text properties such as location.address.text should be rendered. Note: `plain` text can still be multiline. In this case newline symbol (`"\n"`) is used to separate lines. Supported values are: `html` `plain`

For additional information and examples, see Changing Responses with Representation Modifiers.

Response Media Type

Responses to requests to this endpoint will have the urn:nlp-types:autosuggest media type. See the urn:nlp-types:autosuggest media type documentation for details about the structure and content of the response.

Request Example

https://places.sit.ls.hereapi.com/places/v1/autosuggest
?app_id={YOUR_APP_ID}
&app_code={YOUR_APP_CODE}
&at=52.5304417,13.4111201
&q=rest
&pretty

Response Example

{
  "results": [
    {
      "title": "restaurant",
      "highlightedTitle": "<b>rest</b>aurant",
      "category": "restaurant",
      "href": "https://...",
      "type": "urn:nlp-types:search",
      "resultType":"category"
    },
    {
      "title": "rest area",
      "highlightedTitle": "<b>rest</b> area",
      "category": "toilet-rest-area",
      "href": "https://...",
      "type": "urn:nlp-types:search",
      "resultType":"category"
    },
    ...,
    {
      "title": "Restaurant im Fernsehturm",
      "highlightedTitle": "<b>Rest</b>aurant im Fernsehturm",
      "vicinity": "Panoramastraße 1<br/>10178 Berlin",
      "highlightedVicinity": "Panoramastraße 1<br/>10178 Berlin",
      "position": [ 52.52131, 13.40971 ],
      "category": "sights-museums",
      "categoryTitle": "Sights & Museums",
      "href": "https://...",
      "type": "urn:nlp-types:place",
      "resultType":"place"
    },
    {
      "title": "Restaurant Marinelli",
      "highlightedTitle": "<b>Rest</b>aurant Marinelli",
      "vicinity": "Anhalter Straße 1<br/>10963 Berlin",
      "highlightedVicinity": "Anhalter Straße 1<br/>10963 Berlin",
      "position": [ 52.50461, 13.38277 ],
      "category": "restaurant",
      "categoryTitle": "Restaurant",
      "href": "https://...",
      "type": "urn:nlp-types:place",
      "resultType":"place"
    },
    ...,
    {
      "title": "<b>Rest</b>aurant",
      "completion": "aurant",
      "type": "urn:nlp-types:autosuggest",
      "resultType":"query"
    }
  ]
}