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.

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.