Offline Map

VERSION 0.2.1855

Offline functionality for Maps SDK for iOS is only available upon request. Contact us to get started.

This tutorial shows how to build a simple navigation application that works without requiring internet connectivity. It uses the TomTom Maps iOS SDK and Navigation SDKs for iOS. All components are in dedicated modules, available as separate Cocoapods. The engines implement the same interface as their online counterparts but work off a locally stored map.

Getting started

The Navigation SDK for iOS is only available upon request. Contact us to get started.

  1. Install Xcode if you don’t already have it.
  2. Create a new project or open an existing one. The application deployment target has to be set to at least 13.0.
  3. Install Cocoapods on your computer.
  4. Install cocoapods-art tool on your computer.
  5. Because the repository for Navigation SDK is private, you will need to contact us to get access. Once you have obtained access, go to and log in with your account. Expand the user menu in the top-right corner, and select "Edit profile" → "Generate an Identity Token". Copy your token and put it, together with your login, in ~/.netrc. If the file doesn’t exist, create one and add the following entry:
    2login <YOUR_LOGIN>
    3password <YOUR_TOKEN>
  6. Add a reference to the cocoapods-art repository:
    pod repo-art add tomtom-sdk-cocoapods ""
  7. Then create a Podfile in the project folder. The pod init command in the project folder can generate a basic podfile.
  8. At the top of the Podfile add the source of the SDK Cocoapods.
    1plugin 'cocoapods-art', :sources => [
    2 'tomtom-sdk-cocoapods'

Providing access to an offline map

An offline map must be in NDS format and must be stored in an accessible location on the device. Map access is provided through an instance of NDS store. This is achieved by creating an instance of NDSStore, which is part of the TomTomSDKDataManagement module. When creating NDSStore the mapDataPath must point to the directory where the map data is stored, i.e. the directory containing ROOT.NDS, and keystorePath to the keystore SQLite file used to decrypt the map. If the SQLite file is password protected then supply the password in the keystorePassword parameter.

Displaying a map

Once access to an offline map has been setup, it needs to be displayed. This is achieved by creating an instance of the MapDisplayOnboardTileDataProvider class, which is part of the TomTomSDKOnboardMapDisplayDataProvider module. Use the newly created NDSStore object, from the previous section, as a parameter.

1let store = NDSStore(
2 mapDataPath: "mapDataPath",
3 keystorePath: "keystorePath"
5tileDataProvider = try? MapDisplayOnboardTileDataProvider(store: store!)

There are two options to style the offline map:

  1. Style the map using the style provider included in the SDK. The TomTomSDKOnboardStyleProvider module contains the OnboardStyleURLProvider class from which you can access onboard resources.
    1let mainStyle = StyleDefinition(
    2 style: OnboardStyleURLProvider.browsingLightStyleURL,
    3 layerMapping: OnboardStyleURLProvider.layerMappingURL
    5let darkStyle = StyleDefinition(
    6 style: OnboardStyleURLProvider.browsingDarkStyleURL,
    7 layerMapping: OnboardStyleURLProvider.layerMappingURL
    9onboardStyleContainer = StyleContainer(
    10 mainStyle: mainStyle,
    11 darkStyle: darkStyle,
    12 bundle: OnboardStyleURLProvider.resourcesBundle!
  2. Create your own resources and put them into a separate bundle. This bundle should contain:
    • mapbox style file for different modes
    • sprite and sprite atlasses
    • layer mapping JSON file

Create a StyleContainer with URLs pointing to the local resources and bundle. Include the fonts used by the Mapbox style file in the main bundle.

Below is an example of a resource bundle folder structure:

6│ │
7│ └─sprite@2x.json
8│ │
9│ └─sprite@2x.png
10│ │
11│ └─style-browsing.json
12│ │
13│ └─style-driving.json
17 └─sprite@2x.json
19 └─sprite@2x.png
21 └─style-browsing.json
23 └─style-driving.json

Once you have an onboard tile provider and style container, create a TomTomMapView object with MapOptions. Note, the option to cache is not required for offline as the map is stored on the device.

1let mapOptions = MapOptions(
2 mapStyle: onboardStyleContainer,
3 mapKey: "YOUR_API_KEY",
4 cachePolicy: .noCaching,
5 styleMode: .main,
6 tileDataProvider: tileDataProvider
8mapView = MapView(mapOptions: mapOptions)