Autosuggest

Autosuggest in HERE Wego
Figure 1. Autosuggest in HERE Wego

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.

A version of the autosuggest engine is used in the backend of the HERE Wego web application.

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.

Follow-up query

/autosuggest endpoint is meant to support end-user interactions with a text-based input engine. Requests to the /autosuggest endpoints 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.

Query flow
Figure 2. Query flow

WARNING

If apiKey authentication is used, the client must add the apiKey parameter to any query result item returned by autosuggest. See Get Credentials for details on authentication methods.

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 in Berlin would look like:

GET https://autosuggest.search.hereapi.com/v1/
    autosuggest
    ?at=52.5199813,13.3985138
    &limit=5
    &q=res

Authorization: Bearer [your token]

Result items fields

For the previous query "res", autosuggest engine returns the category suggestion "Restaurants", along with a follow-up URI, for the application to use if the user chooses the query suggestion. This query will return restaurant places at the same user location. Additionally, the suggestion engine returns a set of relevant restaurant places. More details about /autosuggest parameters can be found in the API Reference.

The response to the above request looks like the following:

{
  "items": [
    {
      "title": "Hackescher Hof",
      "id": "here:pds:place:276u33db-fb00197ffa5041b2b656ea3d23145dca",
      "resultType": "place",
      "address": { "label": "Hackescher Hof, Rosenthaler Straße 40, 10178 Berlin, Deutschland" },
      "distance": 523,
      "categories": [ { "id": "100-1000-0000", "primary": true }, ... ],
      "foodTypes": [ { "id": "800-064", "primary": true }, ... ],
      "highlights": { "title": [ ], "address": { "label": [ ] } }
    },
    {
      "title": "restaurant",
      "id": "here:cm:ontology:restaurant",
      "resultType": "categoryQuery",
      "href": "http://ci.opensearch.dev.api.here.com/v1/discover?q=restaurant&_ontology=restaurant&at=52.51998%2C13.39851",
      "highlights": { "title": [{ "start": 0, "end": 3 }] }
    },
    {
      "title": "Cordobar",
      "id": "here:pds:place:276u33db-6b5445c1f1854148a8b351822a0ddc0c",
      "resultType": "place",
      "address": { "label": "Cordobar, Große Hamburger Straße 32, 10115 Berlin, Deutschland" },
      "distance": 639,
      "categories": [ { "id": "100-1000-0000", "primary": true }, ... ],
      "foodTypes": [ { "id": "800-064", "primary": true }, ... ],
      "highlights": { "title": [ ], "address": { "label": [ ] } }
    },
    {
      "title": "Zum Nußbaum",
      "id": "here:pds:place:276u33dc-9f17d455cf4145e4be0ac026a10f83bd",
      "resultType": "place",
      "address": { "label": "Zum Nußbaum, Am Nußbaum 3, 10178 Berlin, Deutschland" },
      "distance": 654,
      "categories": [ { "id": "100-1000-0000", "primary": true }, ... ],
      "foodTypes": [{ "id": "302-000", "primary": true }, ... ],
      "highlights": { "title": [ ], "address": { "label": [ ] } }
    },
    {
      "title": "McDonald's",
      "id": "here:pds:place:276u33db-dc6f6db9cef943c1b1ff3f74b30f03f9",
      "resultType": "place",
      "address": { "label": "McDonald's, Friedrichstraße 142, 10117 Berlin, Deutschland" },
      "distance": 703,
      "categories": [{ "id": "100-1000-0009", "primary": true }],
      "foodTypes": [{ "id": "800-067", "primary": true }],
      "highlights": { "title": [ ], "address": { "label": [ ] } }
    }
  ],
  "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:

  • distance - the distance 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.

    New: The primary category has its flag primary set to true.

  • foodTypes - a list of food-type ids if available

    New: The primary category has its flag primary set to true.

Refer to HERE Places Categories and Cuisines for more details.

Query 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.

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.

WARNING

Any undocumented response attribute must be considered experimental and are subject to being removed or modified at any time. Feedback is welcome.

results matching ""

    No results matching ""