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 the following:

• 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.
• 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

There are a several options available to improve the performance on low-end devices, if needed.

For example, you can create custom map styles that contain less elements to render. The more elements are rendered on the map view, the more computing power is consumed by the GPU.

If you want to render multiple POIs on the map, it is better to use MapMarkerLite instances instead of native views like MapOverlay instances that are heavier to render by the native platform.

Load map schemes

The HERE SDK supports several preconfigured map schemes.

Consult the Get Started section to see how to instantly switch default map styles such as satellite versus a normal day map layer.

Add map layers as map features

On top of map schemes, the HERE SDK allows to add certain kinds of layers that show additional information such as the current traffic flow. Check the Traffic section to see an example.

Get informed when the map is ready

The map view can be used as soon as a MapStyle has been loaded successfully. This is indicated by the onLoadScene() callback - as shown in the Get Started section.

Remove unused font files

For the HERE SDK for Android (Lite Edition) it is not necessary to remove font files as it uses fonts that are already part of the Android platform to keep the binary size of the framework as small as possible.

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.

Use the fields mainLanguageCode and fallbackLanguageCode to specify the desired map language via a MapSceneConfig when loading a map scene. The fallbackLanguageCode is used when the desired language is not available in any region of the world. Set both fields to null to switch back to the default behavior.

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.

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.

An absolute cache path and maximum size can be specified when manually initializing the HERE SDK using SDKOptions. Note that the cache path can be also set via the AndroidManifest file. Check the Engines section for more details.

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.

You can also clear the cached data via MapViewLite.

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", "");

It is also possible to specify the cache path from the AndroidManifest.xml file. Consult the API Reference for the SDKNativeEngine to see an example.

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 90 days (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 90 days. 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.