HERE Android SDK Developer's Guide

HERE Map Data

Much of the functionality offered through the HERE SDK depends on HERE Map Data being downloaded and cached on the device. This section describes different approaches that you can take to manage map data download.

Passive Approach

The passive approach is where you allow the SDK to download map data as needed. A typical example is where a user is panning the map, and this triggers on-demand download of the needed map data to render the map.

Map data downloaded in this way is stored in a persistent cache with a limited 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: The map data retrieved by the passive approach is the map data version set by the Map Loader. Therefore, to get the newest map data, Map Loader must be set to the latest version.

Active Approach

HERE SDK provides two alternatives to actively fetch map data:

  • Headless operation to explicitly initiate a fetch for map data by specifying a bounding box or a radius around route.
  • Preloading map data through map packages.

Headless Fetching

The first active approach is where you explicitly trigger a fetch of map data through the available headless APIs by specifying an area defined by a bounding box or radius around a route. As a result, this headless APIs allows you to download the desired map data without relying on actions like panning to implicitly trigger a request. Map data downloaded by headless APIs is stored in a cache with limit size of 256 MB. This is the same cache mentioned in the passive approach section above. When the cache is full and more room is required, any unused map data already in the cache will be removed to make room for the new incoming map data. The SDK does not place a limit on the size of the area to fetch, but it is your responsibility to be aware of this cache limit. This means fetch requests exceeding the cache limit can lead to missing map data within the bounding box or route area. Due to this missing map data, operations that can be done offline such as searching or routing might fail, so it is highly recommended to fetch areas that fall under the 256 MB limit. Provided below are some guidelines to help estimate the size of a fetch to ensure it fits in the cache:

  • As a general rough estimate, for every 100km by 100km, it is about 100 MB, depending on density. A degree of latitude or longitude is approximately 100km.
  • A bounding box the size of 200km by 200km is about 250 MB, encompassing a densely-populated area like New York City. See provided screenshot below.
  • Map data required for a 160km route from New York to Philadelphia with a radius of 500m is about 100 MB. See provided screenshot below.

Choose this active approach if:

  • You desire to have full capabilities of the SDK offline and you predict that a stable online connection will not be available later so on-demand download will not work.
  • Preloaded map packages cover too large an area, and you only desire to fetch the minimal size possible.
  • You desire to avoid managing map packages on the end user’s device.
  • Map data for area of interest can fit in the 256 MB cache. Remember that thse map data will remain in the cache if the map data doesn’t get cleared out with new map data. Therefore, map data retrieved this way is intended to be used where offline capabilities are required for an area, but you require that area only on a temporary basis (for the current session, while navigating through the area, etc). Consider using preloaded map data, if longer persistence is required where an area needs to be available over multiple sessions.
Note: This is a beta feature and not recommended for deployment in applications to end users due to missing capability to check in advance the size of the data (e.g. in kBs) to be downloaded. This limitation will be addressed in a subsequent release.
Note: Note: This approach to fetch map data is recommended to be used with an isolated disk cache.

Preloading

The second active approach is where you explicitly preload map data. 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 England). Preloading map data guarantees that offline operations are possible in cases where a network connection is not available or not desired.

Note: This preloaded map data is stored separately from the map data cache mentioned above. The map data cache only stores map data retrieved via the passive approach and the provided headless APIs.
Note: If map data is needed but not available in one of the preloaded map packages (for example, if a user panned the map to a new country), the SDK dynamically downloads the needed data. This means a device can contain a mixture of preloaded map packages and cached on-demand map data.

Keep Data Up-to-Date

Irrespective of which approach your app supports, it is important that you are aware of your responsibility to ensure that your app is using the latest map data release. HERE releases quarterly (every three months) updates to the map data. You must use SDK APIs to check for map data updates, and if updates are available, trigger the update. It is recommended that your app perform such a check every time it starts. For more information on how to check for map data updates, see the API Reference for the MapLoader class.

Important: Some SDK features may return errors if the map data is more than six months old.
Note: Incremental or patch updates are supported when upgrading from one version to the next version, helping to reduce the amount of data downloaded. Skipping versions may result in a full update and a large amount of data downloaded.