SDK for iOS Developer's Guide

Map Package Download

The second method of getting offline maps capabilities are 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, 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 uninstallMapPackages: 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).

Map Loader Example on GitHub

You can find an example that demonstrates this feature at (Obj-C). (Swift).

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

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 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.