HERE iOS SDK Developer's Guide

Offline Maps (Map Loader)

Applications developed with the HERE iOS SDK have the ability to pre-load map data, allowing the use of maps, search, routing, and other features without an active data connection. Interfaces involved with providing offline maps functionality include NMAMapLoader, NMAMapLoaderDelegate, NMAMapLoaderResult and NMAMapPackage.

The NMAMapLoader and NMAMapLoaderDelegate Interfaces

Offline maps capabilities are enabled through the use of NMAMapLoader and its associated classes. The NMAMapLoader API provides a set of methods which allow manipulation of the map data stored on the device:
  • getMapPackages - To retrieve the current state of the map data on the device through a delegate callback. After this asynchronous operation is complete, the rootPackage property is also populated with the root item of the 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 the 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]

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

  • mapLoader:didUpdateProgress: - Called during NMAMapLoader operations to indicate the current progress of that operation
  • mapLoader:didInstallPackagesWithResult: - Callback associated with the NMAMapLoader installMapPackages: method call
  • mapLoader:didUninstallPackagesWithResult: - Callback associated with the NMAMapLoader uninstallMapPakages: method call
  • mapLoader:didFindUpdate:fromVersion:toVersion:withResult: - Callback associated with the NMAMapLoader checkForMapDataUpdate method call
  • mapLoader:didGetUpdateSize:withResult: - Callback associated with the NMAMapLoader getMapDataUpdateSize method call
  • mapLoader:didUpdateWithResult: - Callback associated with the NMAMapLoader performMapDataUpdate method call
  • mapLoader:didGetMapPackages:withResult: - Callback associated with the NMAMapLoader getMapPackages method call
  • mapLoader:didGetMapPackage:atGeoCoordinates:withResult: - Callback associated with the 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).

The 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 error.
  • 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.

The 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 the installMapPackages method with this package as the parameter, this package's state remains the same, even when the didInstallPackagesWithResult callback occurs. Instead, if you want to retrieve a NMAMapPackage with the latest install state, access the NMAMapLoader rootPackage property. The rootPackage property is updated with a new object instance after every install operation.

Incremental Updates

NMAMapLoader updates the version of the map and provides the freshest map data available. Map data version applies not only to map data pre-installed using the NMAMapLoader, but also to any data which is retrieved dynamically by browsing the map in areas where map data has not been pre-installed. The map version is consistent across all map data, downloaded or not, across the entire system. It is not possible to have some data from one map version and other data from another map version concurrent in the database. Therefore, it is important to keep the map version of the system up to date, which fortunately does not require re-downloading everything. Instead, only the incremental changes need to be downloaded, making typical updates small and quick. Map version updating is exposed through the checkForMapDataUpdate and performMapDataUpdate methods of NMAMapLoader.

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

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.