SDK for Android Developer's Guide

Embedding the Map Service

HERE SDK requires for your app to embed a map service. This map service supports an isolated disk cache, which allows you to set the disk cache to another location such as an SD Card.

  • Migrating the disk cache contents from one location to another is not supported.
  • If you are using an SD card, ensure the SD card is always present to avoid any unexpected behavior.
  • You should only delete the map data cache when the app is in its early start-up stages, before any HERE SDK calls. Otherwise, map data corruption and unexpected app errors can occur.
  • If you plan to support changing the storage location such as switching between internal storage and an SD card, be aware that this requires an app restart, as the storage location switch must be done before initializing MapEngine or AndroidXMapFragment. Also, your manifest entry for the MapService must not contain the process attribute so that the MapService runs in the same process as your app.
    • stopService(new Intent(getBaseContext(), should be called to ensure the map service is shut down properly before the app restarts (for example, using System.exit()), and the disk cache location change can take effect.

The first step to use an isolated disk cache is to edit the AndroidManifest.xml with the following providing the service label and intent name with your custom values.

    <action android:name="{YOUR_INTENT_NAME}">
Note: Always provide custom values for {YOUR_LABEL_NAME} and {YOUR_INTENT_NAME} when you are using an isolated disk cache. Do not reuse HERE SDK defaults.

After editing AndroidManifest.xml add a call to MapSettings.setIsolatedDiskCacheRootPath(String path, String intent) with the desired cache location and the custom intent name. It is recommended to set the disk cache location under your application directory if you do not want the cache to persist after your app is uninstalled. This call should occur before MapEngine initialization. For example, if you are modifying the application from the sample tutorial app, you can add the call in the file before mapFragment.init().

public void onCreate(Bundle savedInstanceState) {

  // Search for the map fragment to finish setup by calling init().
  mapFragment = (AndroidXMapFragment) getSupportFragmentManager().findFragmentById(;
  boolean success =
    getApplicationContext().getExternalFilesDir(null) + File.separator + ".here-maps",
    "{YOUR_INTENT_NAME}"); /* ATTENTION! Do not forget to update {YOUR_INTENT_NAME} */

  if (!success) {
    // Setting the isolated disk cache was not successful, please check if the path is valid and
    // ensure that it does not match the default location
    // (getExternalStorageDirectory()/.here-maps).
    // Also, ensure the provided intent name does not match the default intent name.
  } else {
    mapFragment.init(new OnEngineInitListener() {
Important: Starting with Android O (8.0), the startService() method now throws an IllegalStateException if an app targeting Android 8.0 tries to use that method in a situation when it isn't permitted to create background services. When an app goes into the background, it has a window of several minutes in which it is still allowed to create and use services. For more information, see Android documentation.

Incompatibility with Older Versions

Starting from v3.4 HERE SDK is no longer compatible with pre-3.4 versions of the HERE SDK disk cache. Map data downloaded on pre-3.4 versions of HERE SDK cannot be used on v3.4 or later.

If your app uses the isolated disk cache setting as described above, be aware of the following:
  • When your users update their pre-3.4 HERE SDK apps to a newer version, their previously downloaded data will be unavailable. This occurs regardless of the fact if the app was automatically or manually updated.
  • You can avoid this issue by upgrading the pre-3.4 cache using the DiskCacheUtility.migrate(String sourcePath, String destPath) method. This method takes the same path value as setIsolatedDiskCacheRootPath(String, String), and it must be run before MapEngine is initialized for the first time.
    Note: migrate(String, String) is marked as deprecated because it is offered temporarily to assist with the transition. It will be removed in a future release.
If your app uses the shared disk cache settings as described below, be aware of the following:
  • The required <service>...</service> snippet, as described in the previous section, has changed.
  • When your users update their pre-3.4 HERE SDK apps to a newer version, their previously downloaded data will be unavailable. This occurs regardless of the fact if the app was automatically or manually updated.
  • In the case a user has multiple HERE SDK apps on their system, pre-3.4 apps share one cache, while post-3.4 apps share another.

Using a Shared Disk Cache with the Map Service

Note: This service should be only exported and used by other apps if it is running on Android 7 or below. Starting from Android 8 it is recommended not to export service as it will not be started if the app is in background, so client's MapEngine initialization callback onEngineInitializationCompleted(Error error) will return an error.

On Android 7 and below you can use the map service to facilitate the use of a shared disk cache among applications that use HERE SDK. This service must be embedded and deployed with your HERE-enabled application; otherwise, the MISSING_SERVICE error code is returned via the onEngineInitializationCompleted() callback.

To embed Map Service, add the following lines inside the <application></application> section in your AndroidManifest.xml file:
  android:exported="true" >
    <action android:name="" >