Autosuggest

The /autosuggest endpoint improves the user's search experience by allowing submittal of free-form, incomplete and misspelled addresses or place names to the endpoint.

This suggestion engine is used in the backend of the HERE WeGo and HERE Navigation applications.

Suggestions

Generally speaking HERE Geocoding and Search is meant to provide relevant response to user queries. Queries are either about:

• unknown places of a certain category or chain, like "restaurants" or "starbucks".
• known locations of a certain name, like "Eiffel Tower" or "Berlin"
• unknown places at a known location, like "restaurants Chicago"

Autosuggest is meant to provide relevant suggestions to partial queries, like "restaur", "starbu", "eiffel", or "berl", or even "restaurants chica". Those suggestions are of two kinds:

• query result items

  when relevant follow-up queries are found for the partial query. Those follow-up query items are either

  • place category queries (of result type categoryQuery) or
  • place chain queries (with a type chainQuery).

• entity result items

  when relevant places or address objects are found for the partial query. The result type in that case is one of place, administrativeArea, locality, addressBlock, street, houseNumber.

The "restaurant" suggestion in the above picture is coming from an Autosuggest query result item. The "Restaurant Alpenstueck" suggestion is coming from an entity result item.

Follow-up request

/autosuggest endpoint is meant to support end-user interactions with a text-based input engine. Requests to the /autosuggest endpoint are meant to be sent for each key-stroke, starting with the first one.

Each returned item contains the necessary information to build follow-up queries:

• Query items contain an href element containing a follow-up query to /discover
• Entity items contain a location id usable through the /lookup endpoint

Note that when Autosuggest only returns a query item, applications can proceed with the /discover follow-up query without waiting for the end-users to select it. This is recommended to increase the application responsiveness. Note also that the id field returned in the Query items can not be used on the /lookup endpoint, unlike the id field in the Entity items.

Follow-up to /discover

For example, when HERE WeGo users tap on a query result item like the "restaurant" suggestion in the above picture, HERE WeGo displays the related restaurant search results:

To achieve this, HERE WeGo uses the restaurant suggestion href field to send a follow-up query to the search backend.

When a HERE WeGo user taps on an entity suggestion like the above "Restaurant Alpenstueck", details about the related place are displayed:

To achieve this, HERE WeGo calls /lookup with the related entity result id.

Location context

Queries to /autosuggest need the same kind of location context as /discover, through the use of the at, in or route parameters.

Query string

Additionally, the q parameter is to be used to submit the growing phrases, one Autosuggest query per additional key-stroke.

For instance when an end-user interacts with the application, he/she might intend to enter the letters r, e, s, t, a, u, r, a, n, t. The application would then send a request with a q parameter set to "r", then "re", "res", "rest", etc. The customer can decide to send Autosuggest queries starting with the first key-stroke in order to provide very early suggestions. It can also be decided to only send queries starting with the 3rd key stroke. The example queries would then have a q set to "res", "rest", etc.

Like for discover, the input string can be in various and mixed scripts (Latin, Cyrillic, Arabic, Greek, ...).

Special cases:

• q values are expected to be non-empty.
• q values only containing whitespaces, or tabs, or line feeds are valid queries and return empty results lists.

For instance a query for "res" suggestions somewhere near Neuruppin in Germany would look like:

GET https://autosuggest.search.hereapi.com/v1/
    autosuggest
    ?at=52.93175,12.77165
    &limit=5
    &lang=en
    &q=res
    &apiKey={YOUR_API_KEY}

Result items fields

The suggestion engine returns a set of relevant suggestions, either query or entity items. More details about /autosuggest parameters can be found in the API Reference.

The response to a request similar to the one sent by the HERE WeGo application in the above example looks like the following:

{
  "items": [
    {
      "title": "restaurant",
      "id": "here:cm:ontology:restaurant",
      "resultType": "categoryQuery",
      "href": "https://autosuggest.search.hereapi.com/v1/discover?q=restaurant&_ontology=restaurant&lang=en&at=52.93175%2C12.77165",
      "highlights": { "title": [{ "start": 0, "end": 3 }] }
    },
    {
      "title": "Resort Mark Brandenburg",
      "id": "here:pds:place:276u33j5-6ad49082b9ed4e7bbb88c011d7e8babe",
      "resultType": "place",
      "address": { "label": "Resort Mark Brandenburg, An der Seepromenade 20, 16816 Neuruppin, Germany" },
      "position": { "lat": 52.924, "lng": 12.81321 },
      "access": [{ "lat": 52.9241, "lng": 12.81307 }],
      "distance": 2916,
      "categories": [
        { "id": "500-5000-0000", "name": "Hotel/Motel", "primary": true },
        { "id": "500-5000-0053", "name": "Hotel" },
        { "id": "500-5100-0000", "name": "Lodging" },
        { "id": "500-5100-0059", "name": "Holiday Park" }
      ],
      "chains": [{ "id": "2106" }],
      "references": [ ... ],
      "highlights": { "title": [{ "start": 0, "end": 3 }], "address": { "label": [{ "start": 0, "end": 3 }] } }
    },
    {
      "title": "Hotel & Restaurant am Alten Rhin",
      "id": "here:pds:place:276u33jh-81e655b8ed9246209bcf978fdbcb7db5",
      "resultType": "place",
      "address": { "label": "Hotel & Restaurant am Alten Rhin, Friedrich-Engels-Straße 12, 16827 Neuruppin, Germany" },
      "position": { "lat": 52.95022, "lng": 12.84247 },
      "access": [{ "lat": 52.95026, "lng": 12.84258 }],
      "distance": 5171,
      "categories": [
        { "id": "500-5000-0053", "name": "Hotel", "primary": true },
        ...
      ],
      "references": [ ... ],
      "foodTypes": [ ... ],
      "highlights": { "title": [ ], "address": { "label": [ ] } }
    },
    {
      "title": "Restaurant Rosengarten",
      "id": "here:pds:place:276u33j5-9684ac8171c0408bb0f787b37599548b",
      "resultType": "place",
      "address": { "label": "Restaurant Rosengarten, Wichmannstraße 8, 16816 Neuruppin, Germany" },
      "position": { "lat": 52.92393, "lng": 12.80519 },
      "access": [{ "lat": 52.924, "lng": 12.8053 }],
      "distance": 2411,
      "categories": [
        { "id": "100-1000-0000", "name": "Restaurant", "primary": true },
        ...
      ],
      "references": [ ... ],
      "foodTypes": [ ... ],
      "highlights": { "title": [{ "start": 0, "end": 3 }], "address": { "label": [{ "start": 0, "end": 3 }] } }
    },
    {
      "title": "Restaurant Seegarten",
      "id": "here:pds:place:276u33j5-49777259a2fe4c76a37f8387ca702a6a",
      "resultType": "place",
      "address": { "label": "Restaurant Seegarten, Regattastraße 17, 16816 Neuruppin, Germany" },
      "position": { "lat": 52.91976, "lng": 12.80827 },
      "access": [{ "lat": 52.91978, "lng": 12.80808 }],
      "distance": 2793,
      "categories": [{ "id": "100-1000-0000", "name": "Restaurant", "primary": true }],
      "references": [ ... ],
      "foodTypes": [ ... ],
      "highlights": { "title": [{ "start": 0, "end": 3 }], "address": { "label": [{ "start": 0, "end": 3 }] } }
    }
  ],
  "queryTerms": [ ]
}

Common elements

The response includes multiple items from the top choice to least-likely match. It delivers the following high-level elements for each item:

• resultType - the item type

  HERE Geocoding and Search /autosuggest is able to return items of several types:

  categoryQuery, chainQuery, place, locality, etc.

• title – a representative string for the item

  For instance the name of a place, or the title of a suggestion follow-up query

• id - the identifier of the item

  If the item is not of type categoryQuery, chainQuery, the id value can be used to retrieve the very same object through the /lookup endpoint.

Query results items

Query suggestions specific elements:

• href - follow-up query URI

  This query is to be used by the application if the end user chooses the related item. Follow-up queries are either category queries or chain queries.

• highlights - the text slices matching the query

  These slices can be used to highlight the related matching fields.

Entity results items

Places and address suggestion specific element:

• position - a representative geo-position (WGS 84) of the result. this is to be used to display the result on a map
• access - the geo-position of the access to the result (for instance the entrance)
• distance - the distance in a straight line in meters from the position specified in the query at parameter
• address.label - the full address of the entity result item

Additionally for place suggestions:

• categories - a list of category ids. The primary category has its flag primary set to true.
• foodTypes - a list of food-type ids if available The primary category has its flag primary set to true.
• chains - place chains metadata to allow customers to choose a chain icon

• references - Data source ids, when the place result has a contribution from specific suppliers:

  • yelp, tripadvisor for Yelp and Tripadvisor
  • core for HERE Map Data products with Core POI content (RDF, GDF, NAVSTREETS, File Geodatabase, POI XML)

Refer to HERE Places Categories and Cuisines for more details.

Query term completion support

To support end-users to formulate a free-form textual query, /autosuggest provides a list of complete terms end-users can pick-up to replace the word they began to enter. The list of predictive text for the last entered word is to be found in the queryTerms response element, when the termsLimit query parameter is set to a value larger than 0 (max value is 10).

Note that while items contains result items ready to be used for a complete follow-up query, queryTerms focuses at the query the end-user is being formulating. Both arrays are separated to allow a more flexible application user experience.

A full example is commented in the Query Term Completion chapter.

Preferred language

Applications needing to make sure that items are returned in a preferred language need to set the lang parameter to the related BCP 47 language code. Autosuggest service will do its best to return suggestions in that language. If lang is not set, or if the suggestion item has no translation in the requested language, the default language will be used.