How autocomplete determines which language to use to render a result
This tutorial demonstrates how the geocode /autocomplete
endpoint tries to complete the input text by matching the text terms to parts of an address or an administrative area.
Procedure
The /autocomplete
endpoint tries to detect the query language based on matching name variants and then chooses the same language for the response. Therefore the end-user can see and recognize all the input terms in the same language as in the query. And overall response language is consistent.
Each /autocomplete
result includes a language field with the preferred user language. The value is either the same as specified in the lang
query parameter or if the client application did not provide the parameter, the language that /autocomplete
identified from the input query.
For the languages which in the map data have more than one variant the 2 letter language code is extended as of the map data. For example *-Latn
- for transliterated forms of languages.
In the following example, the user is looking for city Athens, Greece. The user types the city name in English:
GET https://autocomplete.search.hereapi.com/v1/
autocomplete
?q=Athens
&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 /autocomplete
endpoint returns the result in English or, if English is not available for some address components, in the Latin transliteration of the Greek names:
{
"items": [
{
"title": "Greece, Athens",
"id": "here:cm:namedplace:20493491",
"language": "en",
"resultType": "locality",
"localityType": "city",
"address": {
"label": "Athens, Attiki, Greece",
"countryCode": "GRC",
"countryName": "Greece",
"state": "Attiki",
"county": "Attiki",
"city": "Athens"
},
"highlights": {
"title": [
{
"start": 8,
"end": 14
}
],
"address": {
"label": [
{
"start": 0,
"end": 6
}
],
"city": [
{
"start": 0,
"end": 6
}
]
}
}
}
]
}
The /autocomplete
sets the language of the result item to en
- English.
The lang
query parameter allows client applications to specify the preferred response language. If this preferred response language is different from the query input language that /autocomplete
identified, then all matching address fields will still be returned in the same language as in the query. This ensures that users can recognize how the result matches their input. /autocomplete
will return all remaining address fields in the preferred language as specified in the lang
parameter, if available in the map content.
In this case /autocomplete
returns the language
field the same as specified in the lang
query parameter to reflect the preference of the end-user.
In the following example for the address query in Athens the user types the address in transliterated form of Greek language but specifies English as preferred response language:
GET https://autocomplete.search.hereapi.com/v1/
autocomplete
?q=Athina+Stad
&lang=en-US
&apiKey={YOUR_API_KEY}
The /autocomplete
endpoint returns the matched fields in transliterated form of Greek language as it was in the query so that the user can see and recognize them in the response. But it returns all other address components in English. The /autocomplete
sets the language
field for the result item in the response to en
- English:
{
"items": [
{
"title": "Greece, Athina, Stadiou",
"id": "here:af:street:REUzIIKJcWI.MEQiDuUVBA",
"language": "en",
"resultType": "street",
"address": {
"label": "Stadiou, 105 51 Athina, Greece",
"countryCode": "GRC",
"countryName": "Greece",
"state": "Attiki",
"county": "Attiki",
"city": "Athina",
"street": "Stadiou",
"postalCode": "105 51"
},
"highlights": {
"title": [
{
"start": 8,
"end": 14
},
{
"start": 16,
"end": 20
}
],
"address": {
"label": [
{
"start": 0,
"end": 4
},
{
"start": 16,
"end": 22
}
],
"city": [
{
"start": 0,
"end": 6
}
],
"street": [
{
"start": 0,
"end": 4
}
]
}
}
}
]
}
If the input text terms match to multiple languages, the /autocomplete
endpoint returns them in the preferred language, specified by the lang
parameter. The second preference is the country default or the primary regional language.
In the following example the term Berli
matches to multiple languages, including German and Italian. The customer application has specified Italian as preferred response language:
GET https://autocomplete.search.hereapi.com/v1/
autocomplete
?q=Berli
&lang=it-IT
&limit=1
&apiKey={YOUR_API_KEY}
The /autocomplete
endpoint returns the result in Italian. The /autocomplete
sets the language
field for the result item in the response also to it
- Italian language:
{
"items": [
{
"title": "Germania, 10117, Berlino",
"id": "here:cm:namedplace:20187403",
"language": "it",
"resultType": "locality",
"localityType": "city",
"address": {
"label": "Berlino, Germania",
"countryCode": "DEU",
"countryName": "Germania",
"stateCode": "BE",
"state": "Berlino",
"countyCode": "B",
"county": "Berlino",
"city": "Berlino",
"postalCode": "10117"
},
"highlights": {
"title": [
{
"start": 17,
"end": 22
}
],
"address": {
"label": [
{
"start": 0,
"end": 5
}
],
"city": [
{
"start": 0,
"end": 5
}
]
}
}
}
]
}
If the customer application does not specify the lang
parameter, /autocomplete
returns the result in the default language, which is German in this example.
Additional information
For more information about/autocomplete
parameters, see: API Reference.