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

Getting started

Getting started

With the complete set of modules, we give you the possibility to develop map-based applications with a stylable map, customizable UI, and optimized footprint in your favorite technology. The MAP module gives you functionalities for displaying different types and styles of map, map manipulation, map caching, etc.

You can use a comprehensive suite of Map Extensions:

Map UI Extensions to display and customize UI controls for map (e.g., compass, zoom buttons). Map ReactX Extensions to use a ReactX technology in your code. Map Kotlin Extensions to code in Kotlin. Static map image that renders a user-defined, rectangular image containing a map section.

The basic steps for adding the map are:

  • Add a dependency to the map library in build.gradle file:


If you use more than one SDK library, make sure that all libraries have the same version.

  • Enable Java 8 Support in build.gradle file:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
  • Edit the AndroidManifest.xml and add the API key inside the <application> tag:

            android:value="your-tomtom-key" />
  • Embed 'MapFragment' inside your layout:

        android:layout_height="match_parent" />
  • Obtain a reference to the 'MapFragment' and register 'OnMapReadyCallback':


MapFragment mapFragment = (MapFragment) getSupportFragmentManager().findFragmentById(mapFragmentId);
mapFragment = supportFragmentManager.findFragmentById( as MapFragment
  • Forward the permissions callbacks from 'Activity' to 'TomtomMap':

public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    tomtomMap.onRequestPermissionsResult(requestCode, permissions, grantResults);
  • Configure the map once it is ready:


private final OnMapReadyCallback onMapReadyCallback =
        new OnMapReadyCallback() {
            public void onMapReady(TomtomMap map) {
                //Map is ready here
                tomtomMap = map;
private val onMapReadyCallback = OnMapReadyCallback { tomtomMap ->
    val mapPaddingVertical = resources.getDimension(R.dimen.map_padding_vertical).toDouble()
    val mapPaddingHorizontal = resources.getDimension(R.dimen.map_padding_horizontal).toDouble()

        mapPaddingVertical, mapPaddingHorizontal,
        mapPaddingVertical, mapPaddingHorizontal

Map background color

It is possible to change the default color of the Map’s background during initialization. To achieve that there are four options:

  • Passing the param during MapView initialization at xml:

  • Passing the param during MapFragment initialization at xml:

  • Setting the mapBackgroundColor property after MapFragment creation at code:

val mapFragment = MapFragment.newInstance()
            .replace(, mapFragment)
  • Setting it globally by overriding:


<style name="MapBackgroundStyle">
    <item name="android:background">#0000ff</item>


<color name="defaultMapSurfaceColor">#0000ff</color>

New Map Initialization

It is possible to use MapProperties class with its Builder to pass initial properties of the map to either MapFragment or MapView:

val keysMap = mapOf(ApiKeyType.MAPS_API_KEY to "online-maps-key")
val cameraPosition = CameraPosition.builder()
    .focusPosition(LatLng(12.34, 23.45))
val mapProps = MapProperties.Builder()
val fragment = MapFragment.newInstance(mapProps)


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.