Response language

HERE Geocoding and Search aims to provide the result that is readable for the user. To achieve this, HERE Geocoding and Search returns each result in the language specified by the user. Or, if the user has not specified the response language, HERE Geocoding and Search uses for each result its default language. HERE Geocoding and Search returns all address elements in the same language, where available.

Note that this section is applicable to all endpoints, except autocomplete. Refer to Autocomplete for more details.

Default language

In cases where the user does not specify a response language, HERE Geocoding and Search aims to reflect the preference of the local people: it returns results in the official country language. In the regions with the primary regional language different to the official country language, HERE Geocoding and Search prefers the regional one.

In the following example the user is searching for the capital of Greece in English. The user does not specify the preferred response language:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Athens
    &apiKey={YOUR_API_KEY}

HERE Geocoding and Search returns the result in Greek language - the official language of Greece:

{
  "items": [
    {
      "title": "Αθήνα, Αττική, Ελλάδα",
      "id": "here:cm:namedplace:20493491",
      "resultType": "locality",
      "localityType": "city",
      "address": {
        "label": "Αθήνα, Αττική, Ελλάδα",
        "countryCode": "GRC",
        "countryName": "Ελλάδα",
        "state": "Αττική",
        "county": "Αττική",
        "city": "Αθήνα",
        "postalCode": "114 72"
      },
      "position": {
        "lat": 37.97614,
        "lng": 23.7364
      },
      "mapView": {
        "west": 23.68693,
        "south": 37.94882,
        "east": 23.78976,
        "north": 38.03343
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1
        }
      }
    }
  ]
}

Language parameter

All HERE Geocoding and Search endpoints support the lang parameter. The parameter allows the user to set the preferred language of the results. Language code must be provided according to RFC 4647 standard.

For instance, if the user prefers to see all the results in US English, the query shall include lang=en-US:

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Athens
    &lang=en-US
    &apiKey={YOUR_API_KEY}

HERE Geocoding and Search returns the result in English:

{
  "items": [
    {
      "title": "Athens, Attiki, Greece",
      "id": "here:cm:namedplace:20493491",
      "resultType": "locality",
      "localityType": "city",
      "address": {
        "label": "Athens, Attiki, Greece",
        "countryCode": "GRC",
        "countryName": "Greece",
        "state": "Attiki",
        "county": "Attiki",
        "city": "Athens",
        "postalCode": "114 72"
      },
      "position": {
        "lat": 37.97614,
        "lng": 23.7364
      },
      "mapView": {
        "west": 23.68693,
        "south": 37.94882,
        "east": 23.78976,
        "north": 38.03343
      },
      "scoring": {
        "queryScore": 1,
        "fieldScore": {
          "city": 1
        }
      }
    }
  ]
}

Language fallback rules

One primary goal for HERE Geocoding and Search is to provide results in a language and script that the user can recognize and understand.

In cases where some address elements are not available in the requested language, HERE Geocoding and Search returns them in the default language.

But if the default language of the result does not have Latin script and this script is different from the script of the requested language, HERE Geocoding and Search prefers the Latin script - the transliterated form of the country default or the primary regional language.

For instance, the user selects a point on the map in Athens and would like to find the nearest address, but prefers to see the result in US English:

GET https://revgeocode.search.hereapi.com/v1/
    revgeocode
    ?at=37.9782386%2C23.7411506
    &lang=en-US
    &apiKey={YOUR_API_KEY}

The English translations of the country name and the capital city name are available in the map data. HERE Geocoding and Search returns them in English. The streets have only Greek names. Reading Greek script may be difficult to the end-user, therefore HERE Geocoding and Search returns Latin transliterated form of Greek street names:

{
  "items": [
    {
      "title": "10 Anagnostopoulou, 106 73 Athens, Greece",
      "id": "here:af:streetsection:5dzDHBBJbqLpCXyCNTJLUA:CggIBCCO9enIAhABGgIxMA",
      "resultType": "houseNumber",
      "houseNumberType": "PA",
      "address": {
        "label": "10 Anagnostopoulou, 106 73 Athens, Greece",
        "countryCode": "GRC",
        "countryName": "Greece",
        "state": "Attiki",
        "county": "Attiki",
        "city": "Athens",
        "district": "Athens",
        "street": "Anagnostopoulou",
        "postalCode": "106 73",
        "houseNumber": "10"
      },
      "position": {
        "lat": 37.97825,
        "lng": 23.74117
      },
      "access": [
        {
          "lat": 37.97817,
          "lng": 23.741
        }
      ],
      "distance": 2,
      "mapView": {
        "west": 23.73927,
        "south": 37.97765,
        "east": 23.74138,
        "north": 37.98036
      }
    }
  ]
}