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 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 aso that the id field returned in the Query items can not be used on the /lookup endpoint, unline the id field in the Entity items.

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

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": "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 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.

Result details

Autosuggest is typically used in conjunction with a follow-up query on Lookup or Discover. For specific cases, customers need additional details than the ones returned per default. For instance, some applications will need details about addresses or opening hours, and build there own display representation of each result.

To support those applications, HERE Geocoding and Search allows developers to add show=details to their Autosuggest queries. This option exposes the available address details contact information and opening hours information.

Applications not needing these details should not use that option to reduce the result size and spare on the bandwidth, because those details are sent back for each letter added in the user query.

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 ""