Autocomplete: result rendering and highlighting

The /autocomplete endpoint tries to complete the input text by matching the input terms to parts of an address or an administrative area. 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

Authorization: Bearer [your token]

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

Authorization: Bearer [your token]

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

Inclusion and highlighting of the query terms within the result title:
Figure 1. Inclusion and highlighting of the query terms within the result title:

More details about /autocomplete parameters can be found in the API Reference.

results matching ""

    No results matching ""