Autocomplete
The geocode /autocomplete
endpoint is used to speed-up entering the address queries by completion the few entered keystrokes to the valid street address or administrative area. The /autocomplete
responds with suggestions, which include complete addresses and identifiers of the result objects. When the end-user has selected the relevant suggestion, the customer application can subsequently use the /lookup
endpoint to retrieve the geo-coordinates of the suggestion based on the identifier. Alternatively the customer application can use the /geocode
endpoint to geocode the address, returned by /autocomplete
.
The end-user may also select the intermediate result to use it as a base to continue entering the address with help of /autocomplete
. For example, select completion of the city name first, then the street name and specific address on the street.
For example, a query to retrieve a list of addresses, completing the text Pariser 2 Frank
, can be formulated with the following request:
GET https://autocomplete.search.hereapi.com/v1/
autocomplete
?q=Pariser+2+Frank
&apiKey={YOUR_API_KEY}
The response to the above request contains two suggestions, completing the query text, and looks like the following:
{
"items": [
{
"title": "Deutschland, 60486, Frankfurt am Main, Pariser Straße 2",
"id": "here:af:streetsection:A2eGBPgL70TOTtA85fTiEB:CggIBCDg0K_aAhABGgEy",
"language": "de",
"resultType": "houseNumber",
"houseNumberType": "PA",
"address": {
"label": "Pariser Straße 2, 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",
"houseNumber": "2"
},
"highlights": {
"title": [
{
"start": 20,
"end": 25
},
{
"start": 39,
"end": 46
},
{
"start": 54,
"end": 55
}
],
"address": {
"label": [
{
"start": 0,
"end": 7
},
{
"start": 15,
"end": 16
},
{
"start": 24,
"end": 29
}
],
"city": [
{
"start": 0,
"end": 5
}
],
"street": [
{
"start": 0,
"end": 7
}
],
"houseNumber": [
{
"start": 0,
"end": 1
}
]
}
}
},
{
"title": "Deutschland, Frankenthal (Pfalz), Pariser Weg",
"id": "here:af:streetsection:CUcedHTrEUhmgRAcm.mbnD",
"language": "de",
"resultType": "street",
"address": {
"label": "Pariser Weg, 67227 Frankenthal (Pfalz), Deutschland",
"countryCode": "DEU",
"countryName": "Deutschland",
"stateCode": "RP",
"state": "Rheinland-Pfalz",
"countyCode": "FT",
"county": "Frankenthal (Pfalz)",
"city": "Frankenthal (Pfalz)",
"district": "Frankenthal (Pfalz)",
"street": "Pariser Weg",
"postalCode": "67227"
},
"highlights": {
"title": [
{
"start": 13,
"end": 18
},
{
"start": 34,
"end": 41
}
],
"address": {
"label": [
{
"start": 0,
"end": 7
},
{
"start": 19,
"end": 24
}
],
"city": [
{
"start": 0,
"end": 5
}
],
"street": [
{
"start": 0,
"end": 7
}
]
}
}
}
]
}
The response includes the following high-level elements for each result:
resultType
- HERE Geocoding and Search/autocomplete
is able to return items of several types, which cover addresses and areas:houseNumber
,locality
,street
,administrativeArea
,intersection
,postalCodePoint
houseNumberType
- type of address data (returned only for address results):PA
- Point Address, location matches as individual point objectinterpolated
- location was interpolated based on an address range
title
– a representative string for the resultaddress
- the detailed address of the resultid
- the identifier of the result object. Its value can be used to retrieve the very same object through the/lookup
endpoint.language
- the preferred language of address elements in the result. Its value may be used to set the same language preference while retrieving the same object through the/lookup
endpoint by id.highlights
- the text slices matching the query. These slices can be used to highlight the related matching query terms within the result.
More details about /autocomplete
parameters can be found in the API Reference.
The geocode /autocomplete
endpoint tries to complete the entered text by matching the text terms to parts of an address or an administrative area. As it is the "completion" use case, the end-user may expect to see all the already entered terms in the /autocomplete
suggestions. To fulfill this expectation, the /autocomplete
endpoint provides the following features:
- the
/autocomplete
endpoint returns only the results that include all the query terms. The only exception is not matched house numbers. If/autocomplete
can match complete query to a street address, but not the house number, instead of no result/autocomplete
returns street suggestion without a house number. In the example above the second suggestion does not include the house number: it is not available in the map data, but still may be valid in the reality. - the
/autocomplete
endpoint selects the response language so that the end-user can see and recognize all the entered terms in the same language as in the query. With thelang
parameter the customer application can specify the response language preferred by the end-user. It does not change the language of the matched address fields, but sets the language preference for the rest of the address - the result
title
of the/autocomplete
endpoint has format different from all the other end points. It represents the result in unified way, starting from the country name. And includes all the matched query terms - the response includes
highlights
block, which can be used to highlight the matched query terms within the resulttitle
and within the detailed address components in theaddress
block:

Refer to Examples Autocomplete for more details.
NOTE
HERE Geocoding and Search /autocomplete
endpoint does not support premium Japan data.