HERE Map Tile v2 Developer's Guide

Requesting the Right Map Version

The HERE Map Tile v2 offers:

regularly updated maps
different map versions for certain regions of the world to meet the legal requirements in specific countries

The response to an info request lists all the available map versions as elements named map, grouped by the attribute region. The response identifies the most recent map version in each region with the attribute id set to the value "newest". The following excerpt shows an example of a map version list:

<map region="all" id="newest" />
<map region="all" newest="true" id="8.30.53.109" hash="be9b70fa2c" />

Note: The following examples use a HERE API Key to authenticate your request. For the available authentication options, see the Identity & Access Management Developer Guide.

When requesting map tiles, use URL variables to indicate the most recent map or a specific map version:

newest – to request the most recent map version available, for example:

https://2.base.maps.ls.hereapi.com/maptile/2.1/maptile/newest/normal.day/11/1202/843/256/png8
?apiKey={YOUR_API_KEY}

A request to the Traffic base URL should always use newest for the map version, because traffic information is provided only for the latest map. For example:

https://2.traffic.maps.ls.hereapi.com/maptile/2.1/traffictile/newest/normal.traffic.day/11/1202/843/256/png8
?apiKey={YOUR_API_KEY}

a hash value – to request a specific map version; the actual URL variable is the value of the attribute hash from the response to a metadata request (see the response excerpt above). For example, here is a map tile request that uses a hash value instead of /newest/.

Note that the hash values identifying map versions change as a result of software updates, even if the map ids remain the same. To get a valid response to the query, make a metadata request first, and substitute a current map hash value for c376276c01 in the following URL:
```
https://2.base.maps.ls.hereapi.com/maptile/2.1/maptile/c376276c01/normal.day/11/1202/843/256/png8
?apiKey={YOUR_API_KEY}
```

Note: Using newest ensures that the most recent map version available is returned, but it does not guarantee consistency. If for example there is an update in the map data in between a set of requests, some of those requests might return data from the previous map and some from the new map, which might cause an inconsistent map experience. The only way to guarantee a fully consistent map is to use a particular hashcode. Every single request that uses the same hashcode is guaranteed to be consistent with any other request using the same hashcode. Therefore, the usage recommendation is to always use a hashcode in all tile requests, except for traffic. To ensure that the used hashcode is always up to date, query the info page at least every two hours and checking if the hashcode has changed compared to the one previously used. Any particular map version (hashcode) will always be supported for at least 24 hours to ensure a consistent map experience. Note that if the map or software is incorrect, its lifetime might be less than 24 hours to avoid any bad user experiences.

Note: Use the Aerial base URL for all satellite, terrain and hybrid schemes, the Traffic base URL for all traffic and flow requests and the Map base URL for any other requests.

Note: Metadata requests retrieve information specific to the base URLs they target. This information cannot be used in subsequent requests that use other base URLs. For example, to obtain a base map version, use metadata from the response to a request addressed to the Base Map Tiles base URL, but for a version of an aerial map, use metadata from the response to a request addressed to the Aerial Tiles base URL.