Overview

VERSION 2.5.3

The SDK serves map data from an online service and can additionally use an onboard NDS map as a fallback. With the fallback configured, the SDK uses online data whenever it can — connectivity drops are bridged by the prefetched cache — and transparently falls back to onboard data when the cached data can no longer cover the drive. The end user sees an uninterrupted in-vehicle experience.

These guides cover the data that powers navigation: map matching, routing, guidance, and the horizon. Data for the on-screen map is covered by the Map display guides, with one overlap — when the device is offline, the map display also renders from the onboard region store described here.

This page describes the data-source model conceptually. For the code that turns each source on, follow the Map data quickstart.

After reading this page you will know which components serve map data, what their roles are, and where each one is configured.

Use cases

Combining both sources makes navigation agnostic to connectivity. It is the right choice when your product needs:

Always-available map content for navigation when the device is online.
Continued operation — turn-by-turn guidance, map matching, horizon, route replanning, and the map display — when the device stays offline for longer than the prefetched cache can cover, for example on long drives with limited roaming connectivity, or in national parks.
A small storage footprint compared to a fully pre-installed onboard map.

If your users are reliably connected, the online source alone is enough — see the Map data quickstart for running without an onboard fallback.

The two data sources

The SDK combines two map data sources and switches between them transparently. Both are created and managed by the SDK; the Map data quickstart shows how to enable them.

The online source

The SDK streams map tiles from TomTom services and prefetches the tiles around the user’s current position and active route into a bounded persistent cache on the device. This cache is more than a convenience: within the prefetched area the SDK stays fully operational with no connectivity at all — tunnels, parking garages, and longer dead zones do not interrupt the experience. See Caching Strategy for the prefetching, eviction, and freshness mechanics.

The onboard region store

The RegionStore holds NDS map regions on the device and serves them when the online cache can no longer cover the route or position. The onboard map data itself comes from the onboard map setup package that you request from TomTom. You enable it by passing a regionStorePath to buildSdkConfiguration. Omit that argument to run without an onboard fallback.

An onboard region store is not a self-sufficient copy of the full map: it covers only the regions installed in it, and installing regions or keeping them up to date itself requires connectivity. Plan for at least periodic connectivity — for example on WiFi — even in onboard-heavy deployments, or the onboard data drifts out of date. See Manage onboard regions for installing regions and keeping them fresh.

Behavior when connectivity changes

When both sources are configured, the SDK switches between them automatically; there is nothing to additionally configure.

Connectivity state	Behavior
Online	Map data comes from the online source; the cache prefetches the area around the current position, the active route, or where the SDK predicts the drive will go.
Offline — the cache still covers the drive	Operation continues from the cache. No visible change for the driver.
Offline beyond what the cache covers	With onboard data for the trip: the SDK falls back to the onboard region store and the navigation experience continues using onboard data — guidance, horizon, map matching, and the map display. Connection-dependent services — fresh traffic, new routes, search — stay unavailable beyond what was cached. Without onboard data: an active route keeps guiding while cached data for the vicinity lasts.
Online again	The SDK switches back to the online source for fresh data and online services.

If no regionStorePath is configured, the SDK stops serving map data when the cache runs out — there is no onboard fallback to switch to.

How it fits into your app

You only interact with two public types to enable the map data sources:

buildSdkConfiguration(…) — produces an SdkConfiguration that describes where the onboard region store lives (if any) and where caches are written. Presence or absence of the regionStorePath argument controls whether the SDK has an onboard fallback.
TomTomSdk — the SDK entry point. TomTomSdk.initialize(…) consumes the configuration and exposes the runtime objects (TomTomSdk.navigation, TomTomSdk.locationProvider) you compose into your app.

Continue with the Map data quickstart to wire this up in code.

Next steps

Map data quickstart

Initialize the SDK with an onboard fallback and start navigating.

Go to page

Configure map data storage

Choose where the online cache and onboard region store live on the device.

Go to page

Manage onboard regions

Monitor, install, and remove the regions in the onboard region store.

Go to page

Caching strategy

Read how the online cache is prefetched, refreshed, and evicted.

Go to page