Get term suggestions for the last term in the query

This tutorial demonstrates how the API suggests term completion.

Procedure

A user searching for Burger King fast food restaurants in Berlin Mitte on the way from Potsdam would begin to enter the query and get query term completion suggestions in queryTerms, together with 5 location and follow-up query suggestions in items.

For the incomplete query "bur", the query term completion suggestions are for instance "BURGER", "Burgermeister" and "Burg", along with other relevant location suggestions.

See the example below, as well as complete Autosuggest query session example with query terms completion.

GET https://autosuggest.search.hereapi.com/v1/
    discover
    ?at=52.43414,13.19315
    &q=bur&lang=en
    &limit=5
    &termsLimit=3
    &apiKey={YOUR_API_KEY}

{
  "queryTerms": [
    { "term": "BURGER", "replaces": "bur", "start": 0, "end": 3 },
    { "term": "Burgermeister", "replaces": "bur", "start": 0, "end": 3 },
    { "term": "Burgunder", "replaces": "bur", "start": 0, "end": 3 }
  ],
  "items": [
    {
      "title": "BURGER KING",
      "id": "here:pds:place:276u336k-616d8703c79e45c28af2e3c4d322a724",
      "resultType": "place",
      ...
    },
    {
      "title": "Burgermeister",
      "id": "here:pds:place:276u33d9-ae15f7d5f65b470db3c93e9415f895e5",
      "resultType": "place",
      ...
    },
    {
      "title": "Burgunder Straße, 14129 Berlin, Germany",
      "id": "here:af:street:NxklGXv1cSEovzhnxdHxGB",
      "resultType": "street",
      ...
    },
    {
      "title": "Burg, Sachsen-Anhalt, Germany",
      "id": "here:cm:namedplace:20196144",
      "resultType": "locality",
      ...
    },
    {
      "title": "BURGER KING",
      "id": "here:pds:place:276u3364-46972bb96b804b36a83f074d5213cd2e",
      "resultType": "place",
      ...
    }
  ]
}

The following parameters are used:

• at - Specify the center of the search context expressed as coordinates.
• q - Enter a free-text query.
• limit - Maximum number of results to be returned.
• termsLimit - Maximum number of Query Terms Suggestions to be returned.
• apiKey - Your API key.

The end-user would pick-up the "BURGER" suggested term, for the application to replace "bur" with "BURGER" in the q parameter and proceed with the incomplete query. The end-user would then type "k" leading to a "BURGER k" query, to which /autosuggest would return the term suggestion "KING", for the end-user to use.

The example of a complete query typing/completion session appears as follows (BK stands for BURGER KING):

When the end-user chooses the chainQuery suggestion "BURGER KING near Mitte" from the items array, the application fires the related href response element against the Discover service, for the end-user to only get BURGER KING restaurants in Mitte.

The Discover service response to the chainQuery suggestion is:

{
  "items": [
    {
      "title": "BURGER KING",
      "address": {
        "label": "BURGER KING, Alexanderplatz 8, 10178 Berlin, Germany",
        "district": "Mitte",
        ...
      },
      ...
    },
    {
      "title": "BURGER KING",
      "address": {
        "label": "BURGER KING, Friedrichstraße 141, 10117 Berlin, Germany",
        "district": "Mitte",
        ...
      },
      ...
    },
    {
      "title": "BURGER KING Storkower STR. Ecke Landsberger Allee",
      "address": {
        "label": "BURGER KING Storkower STR. Ecke Landsberger Allee, Landsberger Allee 119, 10407 Berlin, Germany",
        "district": "Fennpfuhl",
        ...
      },
      ...
    },
    {
      "title": "BURGER KING",
      "id": "here:pds:place:2768lxx5-3d9439ccf0df01dd9657a0a56254c9cb",
      "resultType": "place",
      "address": {
        "label": "BURGER KING, Schönhauser Allee 79, 10439 Berlin, Germany",
        "district": "Prenzlauer Berg",
        ...
      },
      ...
    },
    {
      "title": "BURGER KING",
      "id": "here:pds:place:276u33db-ad4ba38ca1674569acba3c98b953c532",
      "resultType": "place",
      "address": {
        "label": "BURGER KING, Jean-Monnet-Straße 2, 10557 Berlin, Germany",
        "district": "Moabit",
        ...
      },
      ...
    },
    ...
  ]
}

In this example, by using the query term completion, the end-user has interacted 11 times with HERE Geocoding and Search instead of 18 times for a "Burger King Mitte" query if the application is not integrating the queryTerms elements. The gain can be higher for longer query terms.

Additional information

For more information about /autosuggest parameters, see: API Reference.