Sorry, you need to enable JavaScript to visit this website.



Project set up

To develop your own application with the Maps SDK, you need to make sure that the pre-requisites are in place and that you have added the Maps SDK  as a dependency into your project. Follow the steps below and then you are ready to code! The Maps SDK for Android is compatible with Java and Kotlin.

Get the pre-requisites in place:

  • Android Studio IDE is installed (Android Studio).

  • Set up the application minimum API level to Android 4.4 "Kit Kat" (API Level 19) or higher.

Set up your project like this:

  1. Open the Android Studio IDE.

  2. Create a new project or open an existing one.

Add repositories to all projects to the root/build.gradle:

allprojects {

   repositories {
      maven {
         url ''

Choose the Maps SDK modules for your app

Either independently include modules for Maps, Search, and/or Routing or all of them at once. You can do so by adding the Maps SDK modules to the AndroidManifest.xml and build.gradle.

Configuration for all Maps SDK modules

To include all of the Maps SDK modules in your app, modify AndroidManifest.xml and build.gradle  

  • Key initialization
    Please use dedicated constructors/methods to directly initialize with the Service API Key taken from
    This approach is more thoroughly described in the modules' documentation pages.

  • Modify build.gradle (app/build.gradle)

    //library required to display map
    //library required for search
    //library required for routing
    //library required for traffic
    //library required for geofencing
    //extention library for map custom style and ui support
    //extention library for rx-java2
    //extention library for kotlin support
    //extention library for displaying static map
    //extention library for driving features
  • Enable Java 8 Support in build.gradle (app/build.gradle)

    android {
        compileOptions {
            sourceCompatibility JavaVersion.VERSION_1_8
            targetCompatibility JavaVersion.VERSION_1_8
  • Add MultiDex support if required, as described in MultiDex

Building and Launching

You can build separate APKs for different ABIs to reduce the size of an application. According to Android documentation: Build multiple APKs, just add this to your build.gradle file:

android {
  splits {
    abi {
      enable true

You can also reduce the application size with Android App Bundles.

Maps SDK Examples app

The Maps SDK Examples app is available in two flavors – Kotlin and Java.

Download and build the Maps SDK Examples app to see the key features of the Maps SDK.

Modify the source code to learn more about the SDK.

Speed up development by using the source code in your own app.

The Maps SDK Examples are hosted on github:

Clone repository by command:
git clone

This Maps SDK Examples app is provided by TomTom and subject to TomToms privacy policy at

Developers using TomTom SDKs and APIs in their apps similarly bear responsibility to adhere to the applicable privacy laws.

These Maps SDK Examples are provided as-is and shall be used internally, and for evaluation purposes only. Any other use is strictly prohibited.


TomTom SDK Log level

In TomTom we are constantly working on the quality of our products. That is why it is very important to have logs as detailed as possible for our support team to provide accurate help or bugfixes. The Maps SDK for Android has an advanced mechanism to gather and send logs to our support team. To enable logging and specify a log level please add the following code to your app:


public void onCreate() {
  • android.util.Log.VERBOSE will print all logs from TomTom SDK.

  • android.util.Log.DEBUG will print debug logs from TomTom SDK.

Note: Logs from the SDK libraries are disabled by default.

Collecting logs

TomTom log

Logs from an application can be collected into a file on the SD card.


A special permission should be added into your AndroidManifest.xml file to save logs on the SD card. For example:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

When the sdk-maps module is used, the problem with supporting runtime permissions is handled by the SDK with the following method:


public void onMapReady(@NonNull TomtomMap tomtomMap) {
override fun onMapReady(tomtomMap: TomtomMap) {

Important: Since Android API level 23, it is required to ask the user for runtime permission to write into the SD card.

Register crash observer

Using the crash observer makes it possible to automate the process of preparing an email message with attached logs which were already collected and stored on the SD card. To do so, please register a crash handler with the following code. Crash observer doesn’t break your already-used handlers (like Crashlitics).

LogUtils.registerCrashObserver(getApplicationContext(), Uri.parse("file://" + LOGCAT_PATH), CRASH_OBSERVER_EMAIL);
Bug report

To enable an advanced logging mechanism which collects detailed data from logcat like: threads, services, and phone states, please use the following code:

adb bugreport issue01

This produces an file.


Depending on your project configuration, some dependency conflicts may occur when adding the Maps SDK modules. Here you can find a list of possible issues and tips how to solve them:

  • FindBugs JSF305 conflict:

    Enforce Gradle to compile the fixed FindBugs version for all dependencies. Add the following lines to your app’s build.gradle:

    android {
        configurations.all {
            resolutionStrategy.force ''
  • MultiDex issues should be solved using Google instructions. However, see the following most popular solutions.

    Configure your app for MultiDex. Add the following lines to your app’s build.gradle:

    android {
        defaultConfig {
            multiDexEnabled true

    Add MultiDex support in your app’s build.gradle when minSdkVersion is set to 20 or lower:

    dependencies {
        api ''

    Increase the java max heap size for dex support if required. Add the following lines to your app’s build.gradle:

    android {
        dexOptions {
            javaMaxHeapSize "4g"
  • R8 / ProGuard

    If you are using R8 or ProGuard add the options to your ProGuard file:

    -keep public class** {
        public protected *;