SDK for iOS 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 NMAMapDataPrefetcher and associated classes. The NMAMapDataPrefetcher provides a set of methods to estimate the size of fetches (in KB), initiate fetches, cancel fetches, and clear the map data cache.

NMAMapDataPrefetcher and NMAMapDataPrefetcherListener

NMAMapDataPrefetcher is a singleton which must be obtained using sharedMapDataPrefetcher method. The next code examples show basic NMAMapDataPrefetcher use.

To check for the size of data in advance, use estimateMapDataSizeForBoundingBox:error: or estimateMapDataSizeForRoute:radius:error: methods:

NMAPrefetchRequestError error = NMAPrefetchRequestErrorNone;
NSInteger requestId =
  [[NMAMapDataPrefetcher sharedMapDataPrefetcher]
    estimateMapDataSizeForBoundingBox:bbox error:&error];

To start NMAMapDataPrefetcher fetch, use fetchMapDataForBoundingBox:error: or fetchMapDataForRoute:radius:error:.

NMAGeoBoundingBox* bbox = …
NMAPrefetchRequestError error = NMAPrefetchRequestErrorNone;
NSInteger requestId = [[NMAMapDataPrefetcher sharedMapDataPrefetcher] fetchMapDataForBoundingBox:bbox error:&error];
...

To cancel NMAMapDataPrefetcher fetch, call cancel: method.

NSInteger requestId = ...
[[NMAMapDataPrefetcher sharedMapDataPrefetcher] cancel:requestId];
...

NMAMapDataPrefetcher operations are performed asynchronously. When available, the results of these operations are passed on to NMAMapDataPrefetcher listeners. Listeners must implement the NMAMapDataPrefetcherListener protocol. The callbacks of NMAMapDataPrefetcherListener protocol are:

prefetcher:didUpdateProgress:forRequestId: - Called during map data fetches to indicate the progress completed in the range of [0…1] for a request ID.
prefetcher:didUpdateStatus:forRequestId: - Called during map data fetches to indicate status for a request ID.
prefetcher:didPurgeCache: - Callback to indicate that the cache has been cleared of any unused map data.

NMAPrefetchStatus Enum

NMAPrefetchStatus is an enum data type that represents the status of NMAMapDataPrefetcher fetch operations. This status is returned through the NMAMapDataPrefetcherListener protocol.

NMAPrefetchStatusInProgress - NMAMapDataPrefetcher fetch operation is still in progress
NMAPrefetchStatusSuccess - NMAMapDataPrefetcher fetch completed successfully
NMAPrefetchStatusFailure - NMAMapDataPrefetcher fetch operation failed to complete
NMAPrefetchStatusCancelled - NMAMapDataPrefetcher fetch operation was cancelled

NMAPrefetchRequestError Enum

NMAPrefetchRequestError is an enum data type representing any errors encountered when initiating an NMAMapDataPrefetcher fetch operation.

NMAPrefetchRequestErrorNone – No errors dispatching the request.
NMAPrefetchRequestErrorUnkown – An unknown error has occurred during request submission.
NMAPrefetchRequestErrorBusy – The number of requests is at max capacity.
NMAPrefetchRequestErrorInvalidParameters – The request was invalid due to invalid parameters.
NMAPrefetchRequestErrorOperationNotAllowed – ODML prefetching permission is missing.

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

Incremental Updates

Map data downloaded by specifying a bounding box or a route can be updated to the latest version using NMAMapLoader 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 (e.g. updating from Q2 2017 to Q1 2018), using the NMAMapLoader 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 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.