Map Tile API Developer's Guide

Map Versions

The Map Tile API provides the following methods for specifying which map version you wish to use:
  • request the latest maps using the newest variable
  • request different map versions for specific regions of the world using a hash value

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

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

To use the latest version of a map, use the following GET request:

https://2.base.maps.api.here.com/maptile/2.1/
  maptile/newest/normal.day/11/1202/843/256/png8
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}

To retrieve a specific map version, use the value in the hash attribute from the response to the request to the info resource, such as be9b70fa2c in the example above. In this case, the GET request would be as follows:

https://2.base.maps.api.here.com/maptile/2.1/
  maptile/be9b70fa2c/normal.day/11/1202/843/256/png8
  ?app_id={YOUR_APP_ID}
  &app_code={YOUR_APP_CODE}

The hash value identifying a particular map version may change as a result of software updates, even if the map IDs remain the same. To get a valid response for a request, always make an info request first, and substitute a current map hash value in your subsequent request to the Map Tile (maptile) resource.

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.api.here.com/maptile/2.1/traffictile/newest/normal.traffic.day/11/1202/843/256/png8
    ?app_id={YOUR_APP_ID}
    &app_code={YOUR_APP_CODE}
    

Maintaining Map Consistency

Using the newest property does not guarantee consistency. If there is an update in the map versions between a set of requests to the Map Tile API, you may receive responses with different map versions. This may cause an inconsistent map experience.

To guarantee a fully consistent map, use the same hash value in all tile requests. To ensure that the hash value is always up to date, make your requests to the info resource every two hours, at least, and verifying if the hash value has changed since the last request.

Each map version, represented by the hash value, is supported for a minimum of 24 hours to ensure a consistent map experience. If the map or software is incorrect, its life span may be less than 24 hours to reduce the chances of a bad user experience.