Include time zone information

HERE Geocoding and Search API v7 returns time zone information for result items. This is useful for applications needing to post-process local times, for instance display time differences between the position of the user and a target result.

Time zone data is based on the IANA tz database (also known as the Olson database), which is the industry-standard source for civil time zone definitions worldwide.

Requesting time zone information

To include time zone information in the response, add show=tz to your request. This parameter is supported by all endpoints except the /autocomplete endpoint. For more information on the usage of the show parameter, see Response enrichment.

GET https://geocode.search.hereapi.com/v1/
    geocode
    ?q=Kurfürstendamm+1,+Berlin
    &show=tz
    &apiKey={YOUR_API_KEY}

The response includes a timeZone object in each result item:

{
  "items": [
    {
      "title": "Kurfürstendamm 1, 10719 Berlin, Germany",
      "id": "here:af:streetsection:yYCvdpwmBNB0FoOW0SWGUB:EAIaAzEwMQ",
      "resultType": "houseNumber",
      "address": {
        "label": "Kurfürstendamm 1, 10719 Berlin, Germany"
      },
      "position": {
        "lat": 52.50213,
        "lng": 13.33181
      },
      "timeZone": {
        "name": "Europe/Berlin",
        "utcOffset": "+02:00"
      }
    }
  ]
}

Time zone response fields

The timeZone object contains the following fields:

The utcOffset value reflects the offset in effect at the moment the request is made, meaning it automatically accounts for seasonal transitions between standard time and daylight saving time (summer time).

Time zones in disputed areas

In areas subject to political views, time zone information may differ depending on the politicalView parameter used in the request. For example:

• The disputed territory Rincon de Artigas (-31.01747,-55.96375) is in the time zone America/Montevideo when the query contains a politicalView=URY parameter. Otherwise, it is in the time zone America/Sao_Paulo.
• Likewise, the disputed territory Halaib Triangle (22.24593,36.01012) is in the time zone Africa/Khartoum when the query contains the politicalView=SDN parameter. Otherwise, it is in the time zone Africa/Cairo.

To retrieve time zone information consistent with a specific political view, combine show=tz with the politicalView parameter in your request.

Time zone accuracy

Time zone names are compiled from HERE map data. If a result item does not carry a time zone name in the map data, the API derives the time zone from the geographic coordinates of the result at runtime.

Because time zone rules can change on short notice (for example, when a government abolishes or modifies daylight saving time), the reported UTC offset may briefly differ from the actual local offset if a rule change has been announced but not yet reflected in the underlying data. The IANA tz database is updated multiple times a year to keep pace with such changes.

Convert coordinates to a local time

You can convert car's current coordinates to local time by using the /revgeocode endpoint with show=tz. This is useful when the vehicle crosses time zone boundaries and the head unit clock must stay correct.

Example request (current vehicle location)

GET https://revgeocode.search.hereapi.com/v1/
    revgeocode
    ?at=41.686109,-86.527986
    &show=tz
    &apiKey={YOUR_API_KEY}

To apply the response, read the timeZone.name (for example America/Chicago) as the canonical time zone for the coordinates. Then read the timeZone.utcOffset (for example -05:00) as the offset valid at request time and compute current local time from UTC by applying the offset: localTime = utcNow + utcOffset.

To update the head unit clock, if your platform supports IANA time zones, set the system time zone to timeZone.name and let the OS handle DST transitions automatically.
If your platform only supports fixed UTC offsets, refresh the offset periodically (and after major location changes) to keep time correct across DST changes and border crossings.
Do not infer time zone from state or country alone; near administrative and time zone borders, always rely on the API result for the exact coordinates.

Example response fragment

{
  "items": [
    {
      "position": {
        "lat": 41.686109,
        "lng": -86.527986
      },
      "timeZone": {
        "name": "America/Chicago",
        "utcOffset": "-05:00"
      }
    }
  ]
}