How autocomplete renders a result and how to use highlighting

This tutorial demonstrates how the/autocomplete endpoint tries to complete the input text by matching the input terms to parts of an address or an administrative area.

Procedure

The end-user may expect to see all the already entered input terms in the response and be able easily recognize and select the intent address. To fulfill this expectation, the /autocomplete endpoint renders the result title in a different way than other endpoints.

The /autocomplete renders the result title in a unified way for all the countries starting from the country name and down to the address line. The result title does not always include all the address components. Otherwise it would be too long and overloaded. Only the parts that are important for the end-user to recognize and eventually to choose a result are included.

For example, an intermediate query to find an address on Pariser Straße in Frankfurt could be Frankfurt Pari:

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Frankfurt+Pari
    &limit=1
    &apiKey={YOUR_API_KEY}

The following parameters are used:

• q - Enter a free-text query.
• limit - Maximum number of results to be returned.
• apiKey - Your API key.

The default result title for street results in Germany includes the country name, postal code, city and street name:

{
  "items": [
    {
      "title": "Deutschland, Frankfurt am Main, Pariser Straße",
      "id": "here:af:street:Hg5LQ9NeP5Clua0GQ5dkIB",
      "language": "de",
      "resultType": "street",
      "address": {
        "label": "Pariser Straße, 60486 Frankfurt am Main, Deutschland",
        "countryCode": "DEU",
        "countryName": "Deutschland",
        "stateCode": "HE",
        "state": "Hessen",
        "countyCode": "F",
        "county": "Frankfurt am Main",
        "city": "Frankfurt am Main",
        "district": "Gallus",
        "street": "Pariser Straße",
        "postalCode": "60486"
      },
      "highlights": {
        "title": [
          {
            "start": 13,
            "end": 22
          },
          {
            "start": 32,
            "end": 36
          }
        ],
        "address": {
          "label": [
            {
              "start": 0,
              "end": 4
            },
            {
              "start": 22,
              "end": 31
            }
          ],
          "city": [
            {
              "start": 0,
              "end": 9
            }
          ],
          "street": [
            {
              "start": 0,
              "end": 4
            }
          ]
        }
      }
    }
  ]
}

State and county names in Germany are not so important to recognize the address. Therefore, state and county names are not shown in the result title by default.

But the user may be interested to get suggestions only in state Hessen and use it as part of the query: Frankfurt, Hessen, Pari:

GET https://autocomplete.search.hereapi.com/v1/
    autocomplete
    ?q=Frankfurt%2C+Hessen%2C+Pari
    &apiKey={YOUR_API_KEY}

In addition to the country name, postal code, city and street name, the result title includes the state name:

{
  "items": [
    {
      "title": "Deutschland, Hessen, Frankfurt am Main, Pariser Straße",
      "id": "here:af:street:Hg5LQ9NeP5Clua0GQ5dkIB",
      "language": "de",
      "resultType": "street",
      "address": {
        "label": "Pariser Straße, 60486 Frankfurt am Main, Deutschland",
        "countryCode": "DEU",
        "countryName": "Deutschland",
        "stateCode": "HE",
        "state": "Hessen",
        "countyCode": "F",
        "county": "Frankfurt am Main",
        "city": "Frankfurt am Main",
        "district": "Gallus",
        "street": "Pariser Straße",
        "postalCode": "60486"
      },
      "highlights": {
        "title": [
          {
            "start": 13,
            "end": 19
          },
          {
            "start": 21,
            "end": 30
          },
          {
            "start": 40,
            "end": 44
          }
        ],
        "address": {
          "label": [
            {
              "start": 0,
              "end": 4
            },
            {
              "start": 22,
              "end": 31
            }
          ],
          "state": [
            {
              "start": 0,
              "end": 6
            }
          ],
          "city": [
            {
              "start": 0,
              "end": 9
            }
          ],
          "street": [
            {
              "start": 0,
              "end": 4
            }
          ]
        }
      }
    }
  ]
}

In both cases, the /autocomplete endpoint renders the result label of the address block according to the regional postal rules. These are the same rules for all endpoints. It may not include all the input terms.

The result also includes a block named highlights. The highlights block provides all the information necessary to highlight the matched query terms within the result title and within the detailed address components in the address block.

The result title is composed so that the customer application can use it to render the suggestions with highlighting. For the two above queries, the result is the same, but in second case the title includes state name Hessen, so that the end-user can see all the already entered input terms, highlighted in the result title.

Additional information

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