HERE Android SDK Developer's Guide

Map Package Download

The second method of getting offline maps capabilities are 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 state of the map data 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 running MapLoader operation.

To use MapLoader, you must 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 by way of 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();
mapLoader.addListener(mapLoaderListener);

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 returns 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: The 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 that is used 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 the checkForMapDataUpdate() and performMapDataUpdate() methods.

Data Groups

Map packages are made up 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 the MapLoader.selectDataGroup(SelectableDataGroup) or deselectDataGroup(SelectableDataGroup) method.

Note: This feature can only be used with an isolated disk cache. For more information, see Embedding the Map Service.

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.

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.