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.
Note
This request uses API key authentication. For more information about authentication options on the HERE platform, see the Identity & Access Management Guide.
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.