SDK for Android Developer's Guide

Map Download by Specifying a Bounding Box or Route

Map data can be fetched into a persistent cache (with default size of 256 MB) to enable offline map capabilities by specifying a bounding box or radius around a route. This can be done through the MapDataPrefetcher and associated classes. The MapDataPrefetcher provides a set of methods to estimate the size of fetches (in KB), initiate fetches, cancel fetches, and clear the map data cache.

MapDataPrefetcher and MapDataPrefetcher.Listener Interfaces

MapDataPrefetcher is a singleton that can be obtained using the MapDataPrefetcher.getInstance() method. MapEngine must be successfully initialized before this method can be used. The following examples show basic MapDataPrefetcher use.

To check for the size of the data in advance use estimateMapDataSize(GeoBoundingBox) or estimateMapDataSize(Route, int) methods:

GeoBoundingBox bbox = ...
MapDataPrefetcher.Request request =
  MapDataPrefetcher.getInstance( ).estimateMapDataSize(bbox);
...

To start MapDataPrefetcher fetch use fetchMapData(GeoBoundingBox) or fetchMapData(Route, int):

GeoBoundingBox bbox = ...
MapDataPrefetcher.Request.Error error = MapDataPrefetcher .Request.Error.None;
MapDataPrefetcher.Request request = MapDataPrefetcher.getInstance( ).fetchMapData(bbox);
...

To cancel MapDataPrefetcher fetch call cancelRequest(id)

MapDataPrefetcher.Request request = ...
MapDataPrefetcher.getInstance( ).cancelRequest(request.requestId);
...

MapDataPrefetcher operations are performed asynchronously. When available, the results of these operations are passed on to MapDataPrefetcher’s listeners. Listeners must implement the MapDataPrefetcher.Listener interface to receive notifications while fetches are progressing. Below is a code snippet on adding a listener to the MapDataPrefetcher:

MapDataPrefetcher.Listener mapDataPrefetcherListener = new MapDataPrefetcher.Listener( ) {
  public void onProgress(final int requestId, final float progress) {
  }
  public void onStatus(final int requestId, final PrefetchStatus status) {
  }
  public void onCachePurged(final boolean success) {
  }
  public void onDataSizeEstimated(final int requestId, final Boolean success, final long dataSizeKB) {
  }
};
MapDataPrefetcher.getInstance( ).addListener(mapDataPrefetcherListener);

Note: We provide MapDataPrefetcher.Adapter so you do not need to implement every method in MapDataPrefetcher.Listener.

MapDataPrefetcher.Listener.PrefetchStatus Enum

MapDataPrefetcher.Listener.PrefetchStatus is an enum data type representing the status of MapDataPrefetcher fetch operations. The status is returned through the MapDataPrefetcher.Listener interface.

PREFETCH_IN_PROGRESS - fetch operation is still in progress
PREFETCH_SUCCESS - fetch completed successfully
PREFETCH_FAILURE - fetch operation had failed to complete
PREFETCH_CANCELLED - fetch operation was cancelled

MapDataPrefetcher.Request.Error Enum

MapDataPrefetcher.Request.Error is an enum data type representing any errors encountered when initiating a MapDataPrefetcher fetch operation.

NONE – no errors in dispatching the request
UNKNOWN – an unknown error has occurred during request submission
BUSY – the number of requests is at max capacity
INVALID_PARAMETERS – the request was invalid due to invalid parameters
OPERATION_NOT_ALLOWED – ODML prefetching permission is missing

Check the network connectivity at the application level to ensure MapDataPrefetcher operations are only performed when the device has a connection.

MapDataPrefetcher.Request

MapDataPrefetcher.Request is an object returned when a map data fetch is dispatched. It holds the ID of the request and a MapDataPrefetcher.Request.Error to indicate any errors that occurred.

Incremental Updates

Map data downloaded by specifying a bounding box or a route can be updated to the latest version using MapLoader APIs. 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 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), using the MapLoader APIs to update to the latest version results in the removal of all downloaded map data, whether the data was downloaded on-demand or by specifying a bounding box/route.

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 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 MapLoader.selectDataGroup(SelectableDataGroup) or deselectDataGroup(SelectableDataGroup) method.