SDK for Android Developer's Guide

Map Package Download

The second method of getting offline maps capabilities is enabled through the use of MapLoader and its associated objects. The MapLoader class provides a set of APIs that allow manipulation of the map data stored on the device. Operations include:

  • getMapPackages() - to retrieve the map data state on the device
  • installMapPackages(List<Integer> packageIdList) - to download and install new country or region data
  • uninstallMapPackages(List<Integer> packageIdList) - to uninstall and delete country or region data that is no longer desired
  • checkForMapDataUpdate() - to check whether a new map data version is available
  • performMapDataUpdate() - to perform a map data version update if available
  • cancelCurrentOperation() - to cancel the ongoing MapLoader operation

To use MapLoader you need to call MapLoader.getInstance() to retrieve a MapLoader object instance.

MapEngine must be successfully initialized before this method can be used. MapLoader operations are performed asynchronously. Results of the various operations are returned via a MapLoader.Listener implementation that must be set to listen for notifications from the MapLoader as in the code snippet below:

MapLoader.Listener mapLoaderListener = new MapLoader.Listener() {
  public void onUninstallMapPackagesComplete(MapPackage rootMapPackage,
     MapLoader.ResultCode mapLoaderResultCode) {
  public void onProgress(int progressPercentage) {
  public void onPerformMapDataUpdateComplete(MapPackage rootMapPackage,
     MapLoader.ResultCode mapLoaderResultCode) {
  public void onInstallationSize(long diskSize, long networkSize) {
  public void onInstallMapPackagesComplete(MapPackage rootMapPackage,
      MapLoader.ResultCode mapLoaderResultCode) {
  public void onGetMapPackagesComplete(MapPackage rootMapPackage,
      MapLoader.ResultCode mapLoaderResultCode) {
  public void onCheckForUpdateComplete(boolean updateAvailable,
    String currentMapVersion,String newestMapVersion,
          MapLoader.ResultCode mapLoaderResultCode) {

MapLoader mapLoader = MapLoader.getInstance();

Also, all operations of the MapLoader are mutually exclusive. For example, if method XYZ is called before the callback method ABC has returned a result, method XYZ returns false to indicate that the MapLoader is busy with another operation.

The MapPackage Class

The map data packages available for download are represented as a tree structure with the root map package representing the world map. The MapPackage class represents the model through which this tree structure is accessed. As shown in the preceding code snippet, many of the MapLoader.Listener callbacks return the root MapPackage. The other MapPackage instances are accessed by recursing through the tree structure from the root.

The MapPackage state of a particular instance is not updated dynamically to reflect changes to map data on disk. Therefore if you retrieve MapPackage instance A and then perform an installation operation (which returns MapPackage instance B through onInstallMapPackagesComplete()), MapPackage instance A does not reflect the updated map data state but MapPackage instance B does. Therefore, always use the new MapPackage object returned by a given operation and update the representation in your application accordingly.

Note: getSize() method returns the maximum install size of the map package, in kilobytes. If this is the first MapPackage to be installed, then the package takes up the same amount of memory storage as returned by this method. However, if other packages have already been installed, then the required disk space for this map package is considerably less than the value returned by getSize() because common data between map packages does not need to be installed again. To get an accurate representation of the disk space for a given installation operation use the MapLoader.Listener.onInstallationSize(long, long) callback method.
Note: Map data packages may need to be reinstalled if the application crashes or is forced closed during MapLoader installation or uninstallation.

Incremental Map Data Updates

MapLoader exposes the ability to update the map data version to provide the user with the freshest map data available. The map data version applies not only to map data pre-installed using the MapLoader but also to data downloaded on-demand.

Map data version is consistent for all map data across the entire system, whether the map data is downloaded or not. It is not possible to have some data from one map version and some from another version simultaneously in the disk cache. Therefore, it is important to keep the map version of the system up to date.

You can perform incremental updates if you are updating to the latest map data release from the two previous releases. Incremental updates are typically small downloads as only the changes are downloaded. For example, when updating to the Q1 2018 map data release from the Q4 2017 or Q3 2017 release, an incremental update or patch is used. Where a patch is not available (such as updating from Q2 2017 to Q1 2018), all map data packages are re-downloaded resulting in a much larger download size. Map version updating is exposed through checkForMapDataUpdate() and performMapDataUpdate() methods.

Note: While performing map data update, it is recommended to suspend all HERE SDK functionality that might use map data (such as map panning, searching, routing etc.) and resume when operation if finished.

Data Groups

Map packages consist of several groups each of which contains a different type of map data. Some of these groups may be selected or deselected before map packages are downloaded for offline use depending on the needs of the application. The optional data groups are given in the SelectableDataGroup enum. To select or deselect a data group for download pass the appropriate enum value to MapLoader.selectDataGroup(SelectableDataGroup) or deselectDataGroup(SelectableDataGroup) method.

The selected data groups of the map loader are used for all future installation operations. However, changes to the data group selection do not affect previously installed packages. To update these packages call performMapDataUpdate() after changing the data group selection.

Note: The default data group selection may not be optimal for some applications. To minimize disk space usage, it's recommended that any applications which allow offline map downloads ensure they are only downloading the required data groups. For example, data groups such as TruckAttributes or ScooterAttributes can be excluded if app only supports car.
Note: Disk space that is taken by every data group will wary on the map area and map version. For example, every data group in Berlin/Brandenburg area for Q4 2020 map release takes approximately 5%(20MB) of total size, provided we downloaded package with all available data groups.