HERE SDK for Android (Premium Edition)
In maintenance
SDK for Android 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 to the device in advance. This section describes different approaches you can take to manage map data download.

## Map Data Download Example on GitHub

You can find an example that demonstrates this feature at https://github.com/heremaps/.

## 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 has been downloaded to enable all offline operations, such as offline search or routing.

Note: To ensure the map data version retrieved by passive approach is the latest available, use the MapLoader APIs to update to the latest version.
Note: Use ApplicationContext.setDiskCacheSize(long) 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 MapLoader 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 MapDataPrefetcher 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 size of under this limit. You can get a size estimate of the map data that will be downloaded via the MapDataPrefetcher 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 (1) 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 - 2 GB (2) None (3) 256 MB - 2 GB (2)
Option to check areas for which map data has previously been downloaded (4) 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 (5) Yes No (5)
Can perform incremental updates between map data versions Yes (6) Yes (6) Yes (6)
• (1): Map data downloaded on-demand may support some offline operations such as rendering and search, while others, such as routing, might not work correctly as some essential data may be missing.
• (2): The default value of disk cache upper limit is 256 MB. To change the upper limit of disk cache size use ApplicationContext.setDiskCacheSize(long) 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, thus removing all map data that was downloaded on demand and map data downloaded 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 where map data was not downloaded using the other approaches.

Note: In case of rerouting during turn-by-turn navigation, in the very first time the fast offline rerouting is performed. If it gets failed due to essential data missing, then 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.