SDK for iOS Developer's Guide

HERE Map Data Download

Some key functionality offered through HERE SDK depends on HERE Map Data being downloaded and cached on the device. Rendering a map on the screen, for example, is not possible without first downloading map data to the device. Similarly, it would not be possible to provide accurate turn-by-turn navigation without downloading map data to the device. Offline operations such as offline routing and search also require map data to be downloaded in advance to the device. This section describes different approaches you can take to manage map data download.

Passive Download Approach

The passive approach is where you allow the SDK to download map data as needed. A typical example is when a user pans the map and triggers an on-demand map data download to render the map.

Map data downloaded in this way is stored in a persistent cache with a default size of 256 MB. Cached map data can be used for offline operations in cases where a network connection is not available or not desired, such as when the device is in roaming mode. However, there is no way for you to know if sufficient data have been downloaded to enable all offline operations, e.g. offline search or routing.

Note: To ensure the version of the map data retrieved by the passive approach is the latest version available, use the NMAMapLoader APIs to update to the latest version.

Note: Use [NMAApplicationContext setDiskCacheSize:NSUInteger] to change the default disk cache size.

Active Download Approach

HERE SDK provides two alternatives to actively fetch map data:

Map data may be downloaded in the form of map packages for a predefined region or country.
Map data may be downloaded for an arbitrary bounding box or a radius around a route.

The first active approach is where you request the download of map data packages which cover an entire country or region using the NMAMapLoader APIs. You do this by selecting from a list of map packages. A map package may be a state (such as California), region, or a country (such as Belgium).

Note: This preloaded map data is stored separately from the map data cache mentioned in the passive download approach above. The amount of space available for map data packages is only limited by the amount of free space on the device.

The second active approach is where you explicitly trigger a fetch of map data through the NMAMapDataPrefetcher APIs by specifying a bounding box or a radius around a route. The resulting downloaded map data is stored in the same cache used in the passive download approach, where the cache size by default is 256 MB. The SDK does not place a limit on the size of the area requested for download but it is expected developers are aware of this cache limit and only request areas that result in map data download with size under this limit. You can get a size estimate of the map data that will be downloaded through the NMAMapDataPrefetcher APIs.

To illustrate how much data may be downloaded, consider a bounding box covering an area of 200 km by 200 km in New York City as illustrated in the following screenshot. In this case approximately 250 MB of map data is downloaded.

The next example shows a 160 km route from New York to Philadelphia with a radius (route corridor width) of 500 m. The map data downloaded is about 100 MB.

A comparison of the different approaches for downloading map data is shown below:

Table 1. Map Data Download Approaches
	Passive Approach	Active Approach
	On-demand	Map Packages	Bounding Box / Route
Downloaded map data can be used for offline operation	Limited ⁽¹⁾	Yes	Yes
Complexity involved in managing downloads	None	Medium	Low
Size of map data downloads	Medium (10s of MBs)	Large (100s of MBs)	Medium (10s of MBs)
Upper size limit of cache where data is stored (2)	256 MB - 2GB (2)	None ⁽³⁾	256 MB - 2GB (2)
Option to check areas for which map data has previously been downloaded ⁽⁴⁾	No	Yes	No
Option to check in advance the size of map data to be downloaded	No	Yes	Yes
Option to selectively remove downloaded map data	No ⁽⁵⁾	Yes	No ⁽⁵⁾
Can perform incremental updates between map data versions	Yes ⁽⁶⁾	Yes ⁽⁶⁾	Yes ⁽⁶⁾

(1): Map data downloaded on-demand may support some offline operations such as rendering and search while others, such as routing, do not work correctly as some essential data are missing.
(2): The default value of disk cache upper limit is 256 MB. To change the upper limit of disk cache size use [NMAApplicationContext setDiskCacheSize:NSUInteger] method.
(3): The number of map data packages which can be downloaded is only limited by the space available on the device.
(4): For example, if you want to display to the user what map data has been downloaded and is available for offline use.
(5): Only option is to completely clear the cache using MapDataPrefetcher APIs removing all map data downloaded on demand and by specifying a bounding box or route. Downloaded map packages are not removed.
(6): Incremental updates are available when 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, and map data that was downloaded on-demand or by specifying a bounding box/route is removed.

Many applications may use a combination of all three approaches. For example, a UI may be provided to allow users to select map packages to download. Also, an option may be provided to download map data for a route prior to starting turn-by-turn navigation. Map data download on-demand would always be available as a fallback for the case when map data was not downloaded using the other approaches.

Note: In case of rerouting during turn-by-turn navigation at the very first time fast offline rerouting is performed. If it fails due to missing essential data, online request is sent to create a new route. For fast and reliable rerouting we recommend to have map data for a route downloaded prior to starting turn-by-turn navigation.