Offline map setup

This guide expands upon the basic map configuration setup explained in the Offline map quickstart. It provides additional use cases and more detailed explanations of the various configurations.

In this guide, you will see how to set up the geopolitical view, configure automatic map updates, and monitor offline map events. The code snippets in this guide reuse examples from the Offline map quickstart.

Configuring geopolitical view

Boundary disputes and unsettled land claims exist between nations. These issues can lead to government prohibition of maps and devices that deviate from the local interpretation of the situation.

The geopoliticalView parameter can be provided in the NdsStoreConfiguration to specify which view on disputed areas should be used:

1val ndsStoreConfig =
2    NdsStoreConfiguration(
3        ndsStorePath = mapDir,
4        keystorePath = keystorePath,
5        accessPermit = NdsStoreAccessPermit.MapLicense("YOUR_MAP_LICENSE"),
6        geopoliticalView = "NLD", // Netherlands' view
7    )

The unified international geopolitical view is used if no national view is provided, or if no geopolitical view is defined in the map for the given nation.

Configuring offline map updates

To keep the offline maps up to date, TomTom supports over-the-air (OTA) updates. OTA updates require an internet connection. Since this connection may be metered and could incur costs for the end user, managing offline map updates is important. Our SDK provides two options for managing offline map updates: automatic and manual. These options can work in parallel. The SDK provides the tools needed to configure and adjust the trade-offs to your specific use cases.

You can configure update parameters through the NdsStoreUpdaterConfiguration.

By default, the SDK uses the TomTom production update server. However, this can be configured to any update server. If the server requires an API key, it must be provided in the configuration.

1val customServerUpdateConfig: NdsStoreUpdaterConfiguration =
2    defaultUpdateConfig.copy(
3        updateServerUri = Uri.parse("https://YOUR_SERVER_URI"),
4        updateServerApiKey = "YOUR_TOMTOM_API_KEY",
5    )

Configuring automatic map updates

Automatic map updates leverage the user’s location and planned route to automatically control which map regions are kept up to date. Map regions that are likely to be traversed during a driving session are often referred to as relevant map regions. If the relevant regions are not in the offline map, they are added. If they are already present, they are updated with the latest available data. The SDK identifies relevant regions and checks if new data is available for them. Any automatic updates are executed in the background.

The 'AllRegions' configuration class allows you to set parameters for automatic updates across all regions. The RelevantRegions configuration class lets you configure automatic updates for relevant regions. The RegionsAlongRoute configuration class lets you configure automatic updates for regions along the route.

Relevant map regions can be selected as follows.

To enable the relevant map regions update based on the current location, set the relevantRegions parameter in the AutomaticNdsStoreUpdaterConfiguration.

Additionally, you can customize the radius of the relevant regions and the update interval. For instance, checking for map updates every hour within a 10-kilometer radius of the current location:

1val relevantRegionUpdateConfig: NdsStoreUpdaterConfiguration =
2    defaultUpdateConfig.copy(
3        automaticUpdates = AutomaticNdsStoreUpdaterConfiguration(
4            relevantRegions =
5                RelevantRegions(
6                    radius = Distance.kilometers(10.0),
7                    updateInterval = 60.minutes,
8                ),
9        ),
10    )

To configure the relevant map regions along the route, set the regionsAlongRoute parameter in the AutomaticNdsStoreUpdaterConfiguration. Additionally, you can specify the radius around the route. For example, 5 km:

1val alongRouteUpdateConfig: NdsStoreUpdaterConfiguration =
2    defaultUpdateConfig.copy(
3        automaticUpdates = AutomaticNdsStoreUpdaterConfiguration(
4            relevantRegions = RelevantRegions(radius = Distance.kilometers(5.0)),
5            regionsAlongRoute = RegionsAlongRoute(radius = Distance.kilometers(5.0)),
6        ),
7    )

Relevant map regions are updated with no restrictions on connectivity type—meaning they can also download data over metered network connections (such as mobile data).

NOTE: Configuring a larger radius results in more map regions being considered for updates. Updating more regions increases network data consumption and expands the disk space usage of the offline map. This configuration must be tuned based on the needs of the end users.

• In addition to the relevant map regions options, automatic map updates can also be configured to keep all map regions up to date.

That can be enabled as part of the configuration:

1val allRegionsUpdateConfig: NdsStoreUpdaterConfiguration =
2    defaultUpdateConfig.copy(
3        automaticUpdates = AutomaticNdsStoreUpdaterConfiguration(allRegions = AllRegions()),
4    )

In this case, all map regions in the offline map are considered for updates, in no particular order. This type of automatic map update is currently restricted to run only on unmetered network connections (such as wireless networks).

NOTE: Because all regions available in the offline map are installed and updated, this configuration can significantly increase data usage and offline map disk size.

Limiting use of expensive network connections

When using automatic map updates around the current position and/or along the route, the use of a metered network connection can be limited. A metered network connection is assumed to be expensive, in the sense that someone pays for the data transferred over it. The platform determines which connections are considered metered. In the context of mobile phone usage, mobile data is considered metered, wheras Wi-Fi is not.

There are three possible settings for the use of metered network connections:

• Always allow metered connections (this is the default).
• Never allow metered connections.
• Allow based on data age — allow metered connections for a region if its data is older than a specified duration.

The age-dependent setting allows map regions to be updated over metered connections if the timestamp of their data is older than a specified Duration. This timestamp is the time when the map data was compiled.

To configure this, set the networkConnectivity parameter in the RelevantRegions and/or RegionsAlongRoute configurations.

1val relevantRegionUpdateConfig: NdsStoreUpdaterConfiguration =
2    defaultUpdateConfig.copy(
3        automaticUpdates = AutomaticNdsStoreUpdaterConfiguration(
4            relevantRegions =
5                RelevantRegions(
6                    radius = Distance.kilometers(50.0),
7                    updateInterval = 30.minutes,
8                    networkConnectivity = NetworkConnectivityConfiguration(183.days),
9                ),
10        ),
11    )

The NetworkConnectivityConfiguration class has two constructors. One that takes a Boolean to always or never allow metered connections, and one that takes a Duration to allow metered connections for map regions older than the given Duration.

NOTE: When using the age-dependent setting, it is strongly recommended to choose an age that is at least twice the expected update frequency of the project. If the age is too short, the feature may not work as intended. At the moment when new map updates become available, existing data may already be considered too old. For example, with quarterly updates an age of 6 months to 1 year is recommended.

Updating current position and active route

To ensure that the NdsStoreUpdater can identify relevant map regions, you need to update the current position or the active route, depending on the update strategy:

• For relevant regions updates around the current position, use the updatePosition API to update the current position.
• For relevant regions updates along the route, use the updateActiveRoute API to update the active route.

You can get or subscribe to the current location using the LocationProvider. To set up the LocationProvider, see the Location Provider Quickstart.

1locationProvider.addOnLocationUpdateListener {
2    ndsStoreUpdater.updatePosition(it.position)
3}
4locationProvider.enable()

Limiting the map size

Modern offline maps contain a significant amount of data, and automatically installing new map regions will consume additional disk space. To limit this, you can specify a maximum size for the offline map. If no limit is specified, the offline map can use all available disk space. That is acceptable if the offline map is on a separate partition, but if other data is stored on the same partition as the offline map, it is recommended to set a disk usage limit.

The mapDiskUsageQuota parameter can be provided in the NdsStoreUpdaterConfiguration to specify this limit.

1val diskQuotaUpdateConfig: NdsStoreUpdaterConfiguration =
2    defaultUpdateConfig.copy(
3        mapDiskUsageQuota = Memory.gibibytes(5),
4    )

NOTE: This quota limits only the size of the map itself. It does not limit the size of the downloaded update files needed for the update process. However, since the downloaded update files are removed after they are applied, the update files are not expected to contribute significantly to the long-term disk usage.

During automatic updates of relevant regions or regions along the route, it is possible to automatically remove less useful regions from the offline map if the quota is exceeded or disk space is full.

To specify the behavior when disk space runs out or the quota is exceeded, use the dataRemovalStrategy parameter in the AutomaticNdsStoreUpdaterConfiguration. There are two options:

1val relevantRegionUpdateConfig: NdsStoreUpdaterConfiguration =
2    defaultUpdateConfig.copy(
3        automaticUpdates = AutomaticNdsStoreUpdaterConfiguration(
4            relevantRegions =
5                RelevantRegions(
6                    radius = Distance.kilometers(50.0),
7                    updateInterval = 30.minutes,
8                ),
9            dataRemovalStrategy = DataRemovalStrategy.CompleteRemoval,
10        ),
11    )

• Disabled - No regions are removed, and the update fails. This is the default.
• CompleteRemoval - Removes map regions one by one until enough space is available for the update, or no more regions can be removed.

A region is a candidate for removal if it is not a relevant region (close to the current position) or a region along the current route. Candidates are sorted based on two criteria, in order of importance:

1. The version of the region. Regions with lower versions are considered first, as they are not recently updated and therefore less relevant.
2. The distance from the current position. Farther regions are considered first.

NOTE: When automatically updating all regions, automatic removal is not possible, as all regions are being updated.

Enabling/disabling map updates

Use the setUpdatesEnabled API to enable/disable updates. If updates are disabled during ongoing map operations, those operations are interrupted.

ndsStoreUpdater.setUpdatesEnabled(true)

Next steps

Since you have learned about offline maps and how to set them up, here are recommendations for the next steps:

• Manual Map Management
• TomTom Example App Guide