SDK for iOS Developer's Guide

Map Package Download

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

getMapPackages - To retrieve the current state of the map data on the device through a delegate callback. After this asynchronous operation is complete, rootPackage property is also populated with the root item of package hierarchy
getMapPackageAtGeoCoordinates: - To find the smallest NMAMapPackage containing a given set of geocoordinates
installMapPackages: - To request the specified list of NMAMapPackage to be installed
uninstallMapPackages: - To request the specified list of NMAMapPackage to be uninstalled
checkForMapDataUpdate - To check whether a new map data version is available
getMapDataUpdateSize - To get the size of a pending map data version update
performMapDataUpdate - To perform a map data version update, if available
cancelCurrentOperation - To cancel the running MapLoader operation

NMAMapLoader is a singleton which must be obtained using sharedMapLoader method. The following code example shows basic NMAMapLoader use:

Initiate NMAMaploader

- (void) initMapLoader
{
  NMAMapLoader *mapLoader = [NMAMapLoader sharedMapLoader];
  mapLoader.delegate = self;
  ...
  [[NMAMapLoader sharedMapLoader] getMapPackages];
  ...
 }

Install a map package

- (void) startInstall
{
  ...
  NSArray *packageArray = [[NSArray alloc]
    initWithObjects:packageToModify, nil];
  [[NMAMapLoader sharedMapLoader]
    installMapPackages:packageArray];
  ...
}

NMAMapLoader operations are performed asynchronously. When available, the results of these operations are passed on to the map loader delegate. The delegate is accessed via NMAMapLoader delegate property, and it must implement the NMAMapLoaderDelegate protocol. The callbacks of NMAMapLoaderDelegate protocol are:

mapLoader:didUpdateProgress: - Called during NMAMapLoader operations to indicate the current progress of that operation
mapLoader:didInstallPackagesWithResult: - Callback associated with NMAMapLoader installMapPackages: method call
mapLoader:didUninstallPackagesWithResult: - Callback associated with NMAMapLoader uninstallMapPackages: method call
mapLoader:didFindUpdate:fromVersion:toVersion:withResult: - Callback associated with NMAMapLoader checkForMapDataUpdate method call
mapLoader:didGetUpdateSize:withResult: - Callback associated with NMAMapLoader getMapDataUpdateSize method call
mapLoader:didUpdateWithResult: - Callback associated with NMAMapLoader performMapDataUpdate method call
mapLoader:didGetMapPackages:withResult: - Callback associated with NMAMapLoader getMapPackages method call
mapLoader:didGetMapPackage:atGeoCoordinates:withResult: - Callback associated with NMAMapLoader getMapPackageAtGeoCoordinates: method call
mapLoaderDidLoseConnection: - Callback sent when the NMAMapLoader loses its server connection during an operation
mapLoaderDidFindConnection: - Callback sent when the NMAMapLoader reestablishes its connection

Note: If the app is switched to the background while NMAMapLoader is downloading a map package, the download continues to run in the background for a maximum of three minutes. If the download was not completed within this time, then the download resumes when the app becomes active again.

Note: If a map loader operation is interrupted due to a connection loss, it automatically resumes when the connection is restored (assuming that the operation is not explicitly cancelled during this time).

Map Loader Example on GitHub

You can find an example that demonstrates this feature at https://github.com/heremaps/ (Obj-C) and https://github.com/heremaps/ (Swift).

NMAMapLoaderResult Enum

NMAMapLoaderResult is an enum data type representing the status for NMAMapLoader operations. The status is returned through the NMAMapLoaderDelegate protocol.

NMAMapLoaderResultSuccess - NMAMapLoader operation was completed without errors.
NMAMapLoaderResultInvalidParameters - NMAMapLoader operation was called with invalid parameters.
NMAMapLoaderResultOperationCancelled - NMAMapLoader operation was cancelled by a call to cancelCurrentOperation.
NMAMapLoaderResultConnectionFailed - a connection to the map data server cannot be made.
NMAMapLoaderResultInitializationFailed - the NMAMapLoader could not be initialized.

It is recommended to check the network connectivity at the application level to ensure NMAMapLoader operations are only performed when the device has a connection.

NMAMapPackage Interface

The map data packages available for download are represented as a tree structure with the root map package representing the world map. The NMAMapPackage interface represents the model through which this tree structure is accessed. The properties of class NMAMapPackage are:

parent
children
packageld
sizeOnDisk
installed

The installed state of a particular NMAMapPackage instance is not updated dynamically to reflect changes to map data on disk. For example, if you retrieve an NMAMapPackage instance with getMapPackages and then call installMapPackages method with this package as the parameter, this package state remains the same even when didInstallPackagesWithResult callback occurs. Instead, if you want to retrieve an NMAMapPackage with the latest install state, access NMAMapLoader rootPackage property. The rootPackage property is updated with a new object instance after every install operation.

Incremental 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 other data from another map version concurrent 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 of NMAMapLoader.

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 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 NMAMapDataGroup enum. To select or deselect a data group for download, pass the appropriate enum value to NMAMapLoader selectDataGroup: or deselectDataGroup: method. isDataGroupSelected: method can be used to query the current selection state of a data group.

The selected data groups of 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 NMAMapDataGroupTruckAttributes or NMAMapDataGroupScooterAttributes 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.