Use the map

One of the core features of the HERE SDK for Android is Mapping, which includes adding a map view, changing the location displayed by the map, and modifying its properties. The primary component of the mapping API is the map view, which is integrated as a View subclass. The map view represents a vector based view to display a map and various properties.

HERE map data is updated on a weekly basis to ensure you always get the freshest map data available. By integrating the map view you can automatically benefit from this. While the map is vector based, you can also integrate custom map tiles from other providers.

To manipulate the map and its properties, it is best to start looking at the Camera section. More features include:

• Map gestures to handle common map gestures and default map behaviors like pan or rotate.
• Map schemes to instantly switch default map styles such as satellite versus normal map layer. More on the available map schemes you can find below.
• Map items to place objects and shapes onto the map and interact with them.
• Custom raster tiles to show custom server images as an additional map layer.
• Custom map styles to fully customize the look of the existing map schemes.

Performance optimization

By default, the MapView is rendered with 60 frames per second (FPS). Via mapView.get/setFrameRate() the maximum frame rate can be adjusted - for example, to reduce CPU / GPU usage on low end devices. It is also possible to deactivate automatic render cycles by setting FPS to 0. Setting negative values has no effect. The value can be set individually per MapView instance - in case your app contains multiple MapView's.

Another option is to use custom map styles that contain less elements to render.

To shrink the size of the HERE SDK framework, unused fonts can be removed before shipping an application.

More options are explained in the Optimization Guide.

Load map schemes

The HERE SDK supports several preconfigured map schemes:

• LITE_DAY: A simplified day version of lite map scheme NORMAL_DAY, featuring fewer map elements and limited color palette.
• LITE_NIGHT: A simplified night version of lite map scheme NORMAL_NIGHT, featuring fewer map elements and limited color palette.
• LITE_HYBRID_DAY: A simplified day version of lite hybrid map scheme HYBRID_DAY, featuring fewer map elements and limited color palette.
• LITE_HYBRID_NIGHT: A simplified night version of lite hybrid map scheme HYBRID_NIGHT, featuring fewer map elements and limited color palette.
• NORMAL_DAY: A lossless scaleable vector base map for usage during daylight.
• NORMAL_NIGHT: A lossless scaleable vector base map for usage during night.
• HYBRID_DAY: A day version of a hybrid scheme combining satellite imagery with vector street network, map labels and POI information.
• HYBRID_NIGHT: A night version of a hybrid scheme combining satellite imagery with vector street network, map labels and POI information.
• SATELLITE: A bitmap based map showing satellite imagery for various zoom stages.
• LOGISTICS_DAY: A day version map scheme with focus on fleet management content.

Note that it is also possible to fully customize your own map styles, except for the satellite imagery.

Use the following code snippet to load a map scheme:

MapScheme mapScheme = MapScheme.NORMAL_DAY;

mapView.getMapScene().loadScene(mapScheme, new MapScene.LoadSceneCallback(){
    @Override
    public void onLoadScene(@Nullable MapError mapError) {
        if (mapError == null) {
            // ...
        } else {
            Log.d(TAG, "Loading of map scheme failed: mapError: " + mapError.name());
        }
    }
});

It is recommended to use the day variants during day time when the surrounding light is brighter. The night variants are optimized for usage when there is less light. For example, an application may switch from day to night scheme when a driver is passing through a tunnel - if you are using the Navigate Edition, you can get notified on changed road attributes to know when you are driving through a tunnel. This allows an application to switch the map scheme on the fly. Note that this is not happening automatically.

The HERE SDK is also not automatically detecting the current time of the day to switch between day and night modes. An application may decide to do this based on the user's configuration or by checking the device clock.

The available map styles are optimized to easily add additional content and overlays onto the base map without visual interference. The map schemes are less colorful and support a clean and neutral tone to maximize readability even in case of color blindness:

• The street network is designed in gray scales and provides a hierarchy through brightness, contrast and widths.
• Colors are overall rather bright set up.
• Key colors are grey, blue, green, white.

In addition, the HERE SDK offers a satellite scheme, that does not contain any labels:

Add map layers as map features

On top of map schemes, the HERE SDK allows to add certain kinds of layers - we call them map features - that show additional information such as the current traffic flow. Below you can see how such layers can be enabled:

Map<String, String> mapFeatures = new HashMap<>();
mapFeatures.put(MapFeatures.BUILDING_FOOTPRINTS, MapFeatureModes.BUILDING_FOOTPRINTS_ALL);
mapFeatures.put(MapFeatures.CONGESTION_ZONES, MapFeatureModes.CONGESTION_ZONES_ALL);
mapFeatures.put(MapFeatures.ENVIRONMENTAL_ZONES, MapFeatureModes.ENVIRONMENTAL_ZONES_ALL);
mapFeatures.put(MapFeatures.EXTRUDED_BUILDINGS, MapFeatureModes.EXTRUDED_BUILDINGS_ALL);
mapFeatures.put(MapFeatures.LANDMARKS, MapFeatureModes.LANDMARKS_TEXTURED);
mapFeatures.put(MapFeatures.ROAD_EXIT_LABELS, MapFeatureModes.ROAD_EXIT_LABELS_ALL);
mapFeatures.put(MapFeatures.SAFETY_CAMERAS, MapFeatureModes.DEFAULT);
mapFeatures.put(MapFeatures.TERRAIN, MapFeatureModes.DEFAULT);
mapFeatures.put(MapFeatures.TRAFFIC_FLOW, MapFeatureModes.DEFAULT);
mapFeatures.put(MapFeatures.TRAFFIC_INCIDENTS, MapFeatureModes.DEFAULT);
mapFeatures.put(MapFeatures.VEHICLE_RESTRICTIONS, MapFeatureModes.DEFAULT);
mapView.getMapScene().enableFeatures(mapFeatures);

Similarly, you can also disable a list of layers like shown below:

List<String> mapFeatures = new ArrayList<>();
mapFeatures.add(MapFeatures.TRAFFIC_FLOW);
mapFeatures.add(MapFeatures.TRAFFIC_INCIDENTS);
mapFeatures.add(MapFeatures.EXTRUDED_BUILDINGS);
mapView.getMapScene().disableFeatures(mapFeatures);

Note that not all feature layers are available for all editions. Take a look at the API Reference to know which layers are supported. Note that adding a layer may have a minimal performance impact on lower-end devices.

Below you can see screenshots for all supported map layers:

Some layers allow to filter the shown content via MapContentSettings:

• MapFeatures.TRAFFIC_INCIDENTS: Use filterTrafficIncidents​(List<TrafficIncidentType> trafficIncidents) to filter the displayed traffic incidents.
• MapFeatures.VEHICLE_RESTRICTIONS: Use filterVehicleRestrictions​(TruckSpecifications truckSpecifications, List<HazardousMaterial> hazardousMaterials, TunnelCategory tunnelCategory) to filter the displayed truck restrictions.

Note: The map layers BUILDING_FOOTPRINTS & EXTRUDED_BUILDINGS are enabled by default on the MapView.

Embedded POIs

Naturally, on the map you can find, by default, several icons for restaurants, public transit and other places of general interest. These POIs are called carto POIs and they can be picked by the user to get more details. You can also control the visibility of these embedded POIs.

Take a look at the map items section for more details.

Get informed when the map is ready

The HERE Rendering Engine will be attached each time after onResume() is called. The OnReadyListener tells you once this happens:

mapView.setOnReadyListener(new MapView.OnReadyListener() {
    @Override
    public void onMapViewReady() {
        // This will be called each time after this activity is resumed.
        // It will not be called before the first map scene was loaded.
        // Any code that requires map data may not work as expected until this event is received.
        Log.d(TAG, "HERE Rendering Engine attached.");
    }
});

Most often, you may not need to wait for this event. For example, map items can be added any time. Once the HERE Rendering Engine is attached, the map will become visible. Only code - such as picking map items from the map view - that requires map data should wait for this event to ensure that you will get the expected results.

Remove unused font files

The HERE SDK contains several font files to render map labels for all supported languages. If you want to optimize the size of the overall app, you can remove selected fonts.

For example, the DroidSansFallback font uses the Simplified Chinese ideographs for shared Unicode code points. It is packaged in the HERE SDK AAR file (which can be opened by appending ".zip" to the file name):

• assets/geoviz/DroidSansFallback.ttf

As another example, if you do not need to render the full set of Japanese characters, you can remove:

• assets/geoviz/NotoSansJP-Regular.otf

You can also remove other files, for example, the Navigate Edition contains voice packages like voice_package_ar-SA used to generate texts with guidance instructions for use in TTS engines.

In order to remove files, you need to edit the app's build.gradle file. In the android { ... } section add aaptOptions. The example below shows how to do this for the three mentioned file examples from above:

android {
  ...
  aaptOptions {
    ignoreAssetsPattern "!voice_package_ar-SA*:!DroidSansFallback.ttf:!NotoSansJP-Regular.otf"
  }  
  ...
}

Note that the size of a font file may range from a few hundred kilobytes to a few megabytes in size. After removing selected fonts your application consumes less space when it is installed on a device. The maximum amount that you can save with these steps is approximately 11 MB.

Set a map language

You can customize the language that is used on the map to show labels for streets, cities and other map data. By default, the local language of a region is used.

Call MapView.setPrimaryLanguage(languageCode) to set the language for the world - or set null to switch back to the default behavior. This will set the language for all instances of MapView. If a language is not supported in any region of the world, the local language for that region is shown instead.

Geopolitical views

The HERE SDK supports multiple geographic political views and disputed borders to show the map boundaries based on an international view (default) or a local country view. The local view affects only particular areas on the map when a border and possession or control is claimed by two or more political entities - usually a country.

You can change the default geopolitical view by setting a three letter language code for the politicalView member accessible via SDKOptions. The supported country codes are accessible on the coverage page.

When set, the map view will show all country boundaries according to the geopolitical view of the country that has been set and the MapView will show the borders accordingly.

Note that this is released as a beta feature.

If you want to change the geopolitical view at runtime, use the following code snippet:

// Optionally, clear the cache, so that changing the options has an immediate effect.
SDKCache.fromEngine(SDKNativeEngine.getSharedInstance()).clearCache(error -> {
    if (error != null) {
      // ...
    }

    SDKOptions options = SDKNativeEngine.getSharedInstance().getOptions();
    options.politicalView = "ARG";
    SDKNativeEngine.getSharedInstance().dispose();

    // Now initialize the HERE SDK again using the new options.
});

Make sure to call this not during any ongoing HERE SDK operation, as setting new options requires also to create a new shared instance. Ideally, set the options and the politicalView only once before initializing the HERE SDK for the first time during the app's lifecycle.

Availability of map data

By default, a few regions in the world including Japan, China and Korea, contain limited map data. To get access to the full map data, please get in contact with your HERE representative.

Map data format

The HERE SDK stores all kind of data in map tiles. This can include data needed for rendering purposes in the map view, but it is not limited to this. For example, map tiles also contain data about places or road attributes that are not visualized on the map view, but are needed for other purposes such as turn-by-turn navigation.

The information that is stored in a map tile is categorized into several layers that hold the information for such distinct topics as traffic or landmarks.

• Under the hood, the Navigate Edition uses the Optimized Client Map (OCM) catalog format which provides a compact, fast and flexible map. The OCM catalog is compiled from HERE Map Content (HMC).
• Internally, the Explore Edition uses a slightly different map format (OMV) which is not supporting the offline use case.

The OCM format allows to store all used data permanently in the device storage or temporary in the map cache. This way, an application can access the same features - regardless if the device is online or not.

More information can be found below. Note that OCM is using a default configuration covering the whole world. For selected areas, this includes only a base map - such as for Japan. Extended map data for Japan with a higher level of details is available through a dedicated configuration on request (see also here):

• Optimized Client Map (Base): https://platform.here.com/data/hrn:here:data::olp-here:ocm/overview
• Optimized Client Map for Japan: https://platform.here.com/data/hrn:here:data::olp-here:ocm-japan/overview

Set Japan map

Once your credentials are enabled by the HERE team, you can set the Japan map HRN string "hrn:here:data::olp-here:ocm-japan" to a DesiredCatalog instance. Then create a new CatalogConfiguration and pass it to sdkOptions.catalogConfigurations.

Note that Japan cannot be set without a default map which is covering the whole world. By default, this is OCM, identified by this HRN value: "hrn:here:data::olp-here:ocm".

private List<CatalogConfiguration> getDefaultCatalogConfigurationWithJapan() {
    List<CatalogConfiguration> catalogConfigurations = new ArrayList<>();

    // We want to start with the latest catalog version.
    boolean ignoreCachedData = true;
    CatalogVersionHint versionHint = CatalogVersionHint.latest(ignoreCachedData);

    String defaultOCMHRN = "hrn:here:data::olp-here:ocm";
    DesiredCatalog defaultOCMCatalog = new DesiredCatalog(defaultOCMHRN, versionHint);
    catalogConfigurations.add(new CatalogConfiguration(defaultOCMCatalog));

    // Specify a rich Japan map, requires special HERE credentials.
    // If the credentials are not enabled for access, the map falls back to the Japan base map.
    String japanOCMHRN = "hrn:here:data::olp-here:ocm-japan";
    DesiredCatalog japanOCMCatalog = new DesiredCatalog(japanOCMHRN, versionHint);
    catalogConfigurations.add(new CatalogConfiguration(japanOCMCatalog));

    return catalogConfigurations;
}

For convenience, you can also get the default configuration like this:

List<CatalogConfiguration> catalogConfigurations = new ArrayList<>();

// By calling getDefault() you will automatically get the latest version
// at the time when the HERE SDK was built.
catalogConfigurations.add(CatalogConfiguration.getDefault(CatalogType.OPTIMIZED_CLIENT_MAP));

// Note: If the credentials are not enabled for access, the map falls back to the Japan base map.
catalogConfigurations.add(CatalogConfiguration.getDefault(CatalogType.OPTIMIZED_CLIENT_MAP_JAPAN));

You can also retrieve the details of a default catalog like shown below:

CatalogConfiguration catalogJapan = CatalogConfiguration.getDefault(CatalogType.OPTIMIZED_CLIENT_MAP_JAPAN);
CatalogIdentifier catalogIdentifier = catalogJapan.catalog.id;
Log.d(TAG, "Japan HRN: " + catalogIdentifier.hrn);
Log.d(TAG, "Japan version: " + catalogIdentifier.version);

Note that Japan is an extended map type that requires the OCM catalog as a base map. If Japan is not set, then the area in Japan is showing limited details on the map view. On top, certain features that require map data, like navigation, may not work as expected. Get in touch with the HERE team to get access to the enriched Japan map data.

Offline maps

All map data can be preloaded before usage (also known as active or explicit downloading) or downloaded during online usage (also known as passive or implicit downloading). Both of these strategies require a network connection for data download, but the explicit strategy allows to prepare data in advance and to consume it when a device doesn't have a network connection - while the implicit strategy uses a cache, which can be overwritten during map usage.

Note that certain HERE SDK features may require a specific map version - as indicated in the related API Reference documentation or in this guide.

This is also relevant for cached map data - see the following section. More information on the map version can be found here.

Auto-Update the map

Can you automatically update to the latest map version, for example, at each application start? Yes, this is possible when you have no installed regions. If you have installed regions, you need to update via mapUpdater.updateCatalog(), see the Offline Maps section. If you have no installed regions, you are ready to go and you can update by setting a CatalogVersionHint.

When creating a CatalogConfiguration, you can set a CatalogVersionHint (see also above):

// We want to start with the latest catalog version.
boolean ignoreCachedData = true;
CatalogVersionHint versionHint = CatalogVersionHint.latest(ignoreCachedData);

In effect, this will auto-update the cached map data on each start when you initialize the HERE SDK. By default, you need to set the OCM identifier of the map (unless you use a custom map, see above):

String defaultOCMHRN = "hrn:here:data::olp-here:ocm";
DesiredCatalog defaultOCMCatalog = new DesiredCatalog(defaultOCMHRN, versionHint);
catalogConfigurations.add(new CatalogConfiguration(defaultOCMCatalog));

And then, as a next step, you can initialize the HERE SDK and set the catalogConfigurations via SDKOptions:

SDKOptions options = new SDKOptions(accessKeyID, accessKeySecret);
options.catalogConfigurations = catalogConfigurations;
try {
    Context context = this;
    SDKNativeEngine.makeSharedInstance(context, options);
} catch (InstantiationErrorException e) {
    throw new RuntimeException("Initialization of HERE SDK failed: " + e.error.name());
}

Keep in mind that this code will not update the cached map data, if there are installed regions on a device. Cached data present on a device - for example, data in the map cache or data cached by PrefetchAroundLocation or PrefetchAroundRouteOnIntervals - will become obsolete if a newer map version is available. Such data will be evicted using a LRU strategy over time - which means, that the cache will not be deleted immediately, but when needed, then newer data will be used and old data will be evicted when the cache is full. Therefore, this has no or only a very limited effect on the start-up time.

In order to automatically update cached OCM-based map data, such as for the Navigate Edition, use the default HRN value: "hrn:here:data::olp-here:ocm" in your DesiredCatalog - as shown in the code snippet above.

With the flag ignoreCachedData you can specify how any cached data that may be present on a device should be treated when trying to update the map version. If set to false, the HERE SDK will auto-update to use the latest version only when there is no cached map data at all (for example, at first install or after clearing the cache) and no installed map data. Otherwise, this will have no effect.

Downgrade the map

You can also hard-select a map version: For example, if you want to start with a specific catalog version - even if it is older than the current one.

List<CatalogConfiguration> catalogConfigurations = new ArrayList<>();
CatalogVersionHint versionHint = CatalogVersionHint.specific(57);

After this, follow the same steps as shown in the previous section when initializing the HERE SDK.

Note that this has only an effect if there is no cached or persisted map data (ie. installed regions). For example, you can clear the cache before leaving an app by calling:

SDKCache.fromEngine(SDKNativeEngine.getSharedInstance()).clearCache(error -> {
    if (error != null) {
        Log.d(TAG, "clearCache failed: " + error.name());
    }
});

For first-time installs this is not necessary - if you do this before showing a map view and before prefetching route data.

Adapt map caching

To better support online and offline use cases, the HERE SDK supports caching of downloaded vector map data. This happens in the background. While interacting with the map, the data is stored locally on the device and can be accessed even when the device loses connection or operates in an offline mode.

The integrated map caching mechanism supports the standard vector based map schemes - satellite images and other raster tiles are also cached, but in a different cache that is not configurable.

Please note that the amount of cached data is limited and will be overwritten with new map data while using the map. In most cases, this is sufficient to give the user the impression of a faster start-up time - as no additional data must be downloaded when you start an app again at the same location as before.

When the cache is full, a least recently used LRU) strategy is applied.

Change path and cache size

• An absolute cache path and maximum size can be specified when manually initializing the HERE SDK using SDKOptions. Check the Engines section for more details.
• Via SDKOptions you can specify the desired cacheSizeInBytes to define the upper bound of the cache in bytes. Make sure to query the available disk space on the device with the available platform APIs.

Note: There can be a separate cache defined for customer raster layers.

This is how you can clear the map cache:

SDKCache.fromEngine(SDKNativeEngine.getSharedInstance()).clearCache(error -> {
    if (error != null) {
        // ...
    }
});

Note that disposing the shared instance of the SDKNativeEngine does not clear the cache.

By setting an empty string as cache path, you keep the default cache path - which is also accessible via context.getCacheDir().getPath() or SDKNativeEngine.getSharedInstance().getOptions().cachePath:

// Specify credentials programmatically and keep default cache path by setting an empty string.
SDKOptions sdkOptions = new SDKOptions("YOUR_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_SECRET", "");

You can update the map cache to a newer map version - independently of offline maps. By calling mapUpdater.performMapUpdate() the map cache will be updated to a newer version (if available) - even if never any Region was installed. If offline maps are available, then they will be updated together with the map cache, like before. If offline maps are installed later after the cache has been updated, the same map version will be used. It is not possible to use different versions for the map cache and offline maps.

In order to get the latest map data while panning the map view, you can check if an update is available and then install it. If no offline Region maps are installed, this takes only a few seconds. The MapVersionHandle indicates the currently used map version.

More information on the map version, the cache and offline maps can be found in the Offline Maps section.

Questions and answers around the map cache

• What is a map tile? Map tiles are stored in the map cache. A map tile contains data relevant for search and routing, as well as vector data for the visual representation. It is stored in the Optimized Client Map (OCM) format. Map tiles are available for different zoom levels. A map tile may contain different data, depending on the zoom level.

• What is the impact of missing data in the map cache? Usually, the map cache is never assumed to be complete and there can be always tiles missing for a surrounding area. This is because map tiles get loaded only on demand while they are rendered. When there are tiles missing from the map cache then, for example, the OfflineSearchEngine will not find POIs or road names that are part of the missing tiles and the HERE Rendering Engine cannot render such data. Also, the OfflineRoutingEngine might fail - unless it finds a route around the missing tiles. Note that the OfflineSearchEngine and the OfflineRoutingEngine are not available for every edition.

• What is the size of the map cache? The size of the map cache can be changed by the application. Use at least 256 MB (default). Values above 512 MB or 1 GB are recommended. For turn-by-turn navigation (which is available e.g. for the Navigate Edition), map tiles of zoom level 14 are needed, which equals a circle of roughly 2 km. However, this can vary a bit from location to location.

• What is the eviction policy of the cache? The HERE SDK uses a LRU (least recently used tile) logic to evict the tiles when the map cache becomes full. There is no sophisticated logic to evict, for example, tiles that are farther away from the current location - as it is not foreseeable which areas of the world the user might visit next. However, the map cache is not session-specific, its data from the last time the device was used, ie. from the last power cycle, is still there the next time the app is used. Note that the cache is specific per app, not per device.

• Is any previously cached map tile searchable offline? Yes, it's always searchable with the OfflineSearchEngine. However, sometimes not every map tile contains the same search results for every zoom level. Note that the OfflineSearchEngine is not available for every edition.

• Is only one map tile cached at a time? Yes, only one tile at a time may be added unless its location is on the edge of two tiles. Depending on the zoom level, rendering of the map view will require several tiles - this is not happening automatically and only when the zoom level changes.

• Are satellite images cached? Yes, when the satellite map scheme is set, the corresponding imagery is also cached, but satellite images cannot be used after 1 day (for contractual reasons) and will be evicted. In this case, the HERE SDK checks if there are newer satellite map tiles available and if yes then the images are automatically updated in the cache. If the images have not been changed, then only the timestamp is updated so that the images can be reused after this check for another period of 1 day. However, the LRU strategy still applies. Note that non-satellite map tiles are only evicted when the cache is full - there is no staleness of old tiles and no automatic deletion of old tiles based on time.

• Is there always "base map" available, such as a globe view? The HERE SDK downloads automatically the world tiles, ie. the top most zoom level tiles for the globe. This means that there is always a map available for the globe with a very limited amount of information for rendering purposes. The shapes of countries and continents are visible and capitols are shown with text labels.

• Is the cache auto-cleared? No, a full cache is only cleared based on a LRU strategy (see above). If tiles have not been fully downloaded due to a connectivity interruption, these tiles are preserved and the download continues when connectivity resumes.

• If connectivity is available, will a whole route be cached in advance? No, this is not happening automatically. However, you can use the RoutePrefetcher to download map data into the cache along the route corridor. Look into the turn-by-turn navigation section for more details. Note that the RoutePrefetcher is not available for every edition.

HERE logo watermark

When using the HERE SDK, it is required that the HERE logo is always visible on the map view. By default, the HERE logo is located at the bottom right corner of the map. However, you can easily customize its location to meet your app design by calling setWatermarkLocation() on your map view instance. It is recommended to change the default placement only when it is required due to overlapping UI elements. Note for very small views: If both edges of the map are less than 250 density independent pixels in size, the watermark will be hidden automatically.

Choose surface or texture view

Depending on your application needs, the MapView supports two different native render modes.

• By default, MapRenderMode.SURFACE is used, which offers the best performance, but may suffer from graphical glitches that may occur on Android 12 and newer.
• For applications with complex and dynamic UI or with multiple MapView instances consider to use MapRenderMode.TEXTURE to avoid graphical glitches. This mode may have a greater performance impact than using the default SurfaceView.

Choose the MapRenderMode via HereMapOptions.renderMode, which allows to set internally a native SurfaceView or TextureView for rendering.

Add support for Android Auto

The HERE SDK can be seamlessly integrated with Android Auto and Android Automotive.

For example, you can use the premium offline & online search capabilities of the HERE SDK to search for places in your car - or integrate a full-blown navigation solution. If you want to show a map view on the Desktop Head Unit, you need to render the map using a MapSurface instance. Follow the Integrate a HERE Map into Android Auto tutorial to see how this can be done.

Customize map data with the CatalogConfiguration

By default, the HERE SDK uses map data that is compiled into a specialized map format. This data is downloaded into the map cache on-the-fly - or it can be downloaded in advance with offline maps. The Navigate Edition uses the OCM map format.

A map is a collection of layers that contain the map data. Each layer contains map objects with geometry and attribution. A layer's content is cut into tiles, for efficient search, map display, routing, map matching, driver warnings and other data. The core map content is divided into regional maps, but can always be used as a single, global map. Other content is delivered in dedicated - mostly worldwide - maps.

This data can be customized together with HERE and then made accessible via a custom catalog. With this you can bring your own data (BYOD) to us. In order to do this, you need to specify the HRN value and scope for your catalog. More information on the HRN catalog identifier and setting a scope can be found here.

On top, you may also want to adapt certain HERE online services such as routing and search to match the data of the offline maps data. In this case, HERE can help to setup a custom backend that hosts the adapted HERE services just for your company. Such a custom backend can be specified via an EngineBaseURL and then all requests that are initiated with, for example, the SearchEngine will use that backend.

A custom CatalogConfiguration along with custom backend URLs needs to be specified via SDKOptions each time the HERE SDK is initialized - as the setting is not persisted.

The below code snippet shows how to do this:

private void initializeHERESDKWithCustomCatalogConfiguration() {
    // Note: Each catalog configuration may require special credentials.
    String accessKeyID = "YOUR_ACCESS_KEY_PROD";
    String accessKeySecret = "YOUR_ACCESS_KEY_SECRET_PROD";

    SDKOptions options = new SDKOptions(accessKeyID, accessKeySecret);

    // Specify one or more custom catalog configurations.
    options.catalogConfigurations = getCustomCatalogConfiguration();

    // Optionally, specify a custom routing backend that matches the custom OCM map for use with the (online) RoutingEngine.
    options.customEngineBaseUrls = getCustomBackends();

    try {
        Context context = this;
        SDKNativeEngine.makeSharedInstance(context, options);
    } catch (InstantiationErrorException e) {
        throw new RuntimeException("Initialization of HERE SDK failed: " + e.error.name());
    }

    SDKNativeEngine.getSharedInstance().setAccessScope(getCustomCatalogScope());
}

private List<CatalogConfiguration> getCustomCatalogConfiguration() {
    List<CatalogConfiguration> catalogConfigurations = new ArrayList<>();

    // We want to start with the latest catalog version.
    boolean ignoreCachedData = true;
    CatalogVersionHint versionHint = CatalogVersionHint.latest(ignoreCachedData);    

    String customHRN = "hrn:here:data::olp-namespace:your-company-ocm";
    DesiredCatalog customOCMCatalog = new DesiredCatalog(customHRN, versionHint);
    catalogConfigurations.add(new CatalogConfiguration(customOCMCatalog));

    return catalogConfigurations;
}

private HashMap<EngineBaseURL, String> getCustomBackends() {
    return new HashMap<EngineBaseURL, String>() {{
        put(EngineBaseURL.ROUTING_ENGINE, "https://byod-your-company.router.hereapi.com");
    }};
}

private String getCustomCatalogScope() {
    return "hrn:here:authorization::olp-here:project/your-company-hsdk";
}

Initially, you need to specify a catalog version you want to start with. The DesiredCatalog provides a way to identify a catalog on the HERE platform. A developer can also specify the HERE Resource Name (HRN) for the catalog along with a CatalogVersionHint for the desired version. Once set up, you can use regular map updates via MapUpdater (not available for all editions). This catalog version will then appear as part of the MapVersionHandle.

Note that such a set-up requires a special agreement with HERE. Please contact your HERE representative for more details.

The HERE Map Attributes API allows to access all HERE map data as well as the private map data of a customer.

Self hosting

With customEngineBaseUrls (see here), it is possible to self host services for the HERE SDK, for example, you can mirror the backend for HERE services on your own servers and access them by setting a URL per EngineBaseURL.

The access to your own backend is fully customizable with configurable endpoints including authentication and proxy support (see here).

Note that this requires quite some effort and it is recommended to get in touch with the HERE SDK support team to discuss your setup and possible alternatives.

Setting a DS proxy

By default, the data service proxy, in short DS_PROXY, is set to "https://direct.data.api.platform.here.com/direct/v1". When a custom catalog should be used, then the HERE SDK will internally do a lookup request to find out the corresponding URL to access a catalog. In order to bypass this extra request, we recommend to set the URL upfront when initializing the HERE SDK.

For example, a valid DS_PROXY for a custom catalog may look like this: "https://data.api.platform.yourcompany.com/direct/v1".

Set the custom proxy via EngineBaseURL and pass it as customEngineBaseUrls to SDKOptions when initializing the HERE SDK.