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



Map initialization

The main class that represents a map is a MapView. MapView is wrapped by MapFragment. To display a map, it is recommended to use`MapFragment`.

The basic steps for adding a map are:

  1. Follow the steps described in the Getting started section.

  2. Add MapFragment to your Activity:

  • MapFragment created from the code:

val mapFragment = MapFragment.newInstance()
  • MapFragment declared in the XML:

    android:layout_height="match_parent" />

To obtain the fragment reference call:


MapFragment mapFragment = (MapFragment) getSupportFragmentManager().findFragmentById(mapFragmentId);
mapFragment = supportFragmentManager.findFragmentById( as MapFragment

  3. Implement the OnMapReadyCallback and use the onMapReady method to get the TomtomMap object:

 * Callback interface executed when the map is ready to be used.
 * The instance of this interface is set to {@link MapFragment},
 * and the {@link OnMapReadyCallback#onMapReady(TomtomMap)} is triggered
 * when the map is fully initialized and not-null.
public interface OnMapReadyCallback {
     * Called when the map is ready to be used.
    void onMapReady(@NonNull TomtomMap tomtomMap);


Sample implementation of the OnMapReadyCallback:


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

Attach OnMapReadyCallback to the MapFragment:



  4. 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);

MapView initialization

In some cases, it may be required to directly use "MapView". To do this create a new instance by calling:

val mapView = MapView(context)

When working with MapView you need to pass lifecycle events as shown in the following example:

public void onStart() {

public void onResume() {

public void onPause() {

public void onStop() {

public void onDestroy() {

public void onSaveInstanceState(@NonNull Bundle outState) {


Map properties

IMPORTANT: In May 2020 the methods used to switch between vector and raster tiles were deprecated and will be removed after one year. From that point, to display raster tiles it will be required to reload the style to one which contains raster layers. Before the deprecation period is over, a map is still going to be initialized with the style that contains raster and vector tiles. However, if your style is obtained from the Style Merger you need to set MapStyleSource to STYLE_MERGER in MapProperties described here.

You can create an instance of the MapProperties class via its Builder to pass initial properties of the map to either MapFragment or MapView. MapProperties is a single point of initialization of different map parameters. It is possible to set the following properties:

Map properties can be specified depending on the implementation of Map:

  • Map background color:

  • Map style url:

  • Map initial camera position:

val cameraPosition = CameraPosition.builder()
    .focusPosition(LatLng(12.34, 23.45))
  • Map initial camera focus area:

val cameraFocusArea = CameraFocusArea.Builder(
    BoundingBox(LatLng(52.407943, 4.808601), LatLng(52.323363, 4.969053))
  • Map initial padding:

    .padding(MapPadding(50.0, 40.0, 100.0, 80.0))
  • TomTom services API Keys:

val keysMap = mapOf(
    ApiKeyType.MAPS_API_KEY to "maps-key",
    ApiKeyType.TRAFFIC_API_KEY to "traffic-key"
  • MapStyleSource is used to determine if the default and loaded style should support Style Merger. Setting it to STYLE_MERGER results in the default style only supporting vector tiles:

  • LayerSetConfiguration is used to provide custom IDs for layer sources in the style. This is useful when the user has a custom style not compliant with the TomTom source names convention. An underlying builder allows the configuration of Map Tiles, Traffic Flow Tiles, and Traffic Incidents Tiles. LayerSetConfiguration should only be used with the MapStyleSource set to STYLE_MERGER.

val layerSetConfiguration = LayerSetConfiguration.Builder()

The MapProperties instance can be passed to either MapFragment or MapView in the following way:

val fragment = MapFragment.newInstance(mapProperties)
val view = MapView(context, mapProperties)

MapProperties can be also declared in the XML:

<fragment xmlns:tomtom=""






    tomtom:trafficApiKey="traffic.api.key" />

When using the Maps SDK for Android, it is required that the TomTom logo is always visible. By default, the TomTom logo is located at the bottom-left corner of the map. However, you can easily customise its position to meet your app design by defining the LogoView style in the style.xml file in your app.

Sample use case 1: Your app has a bottom panel which covers the TomTom logo and you need to place the logo in the top-right corner. To change the TomTom logo position:

<style name="LogoView" parent="BaseLogoView" >
    <item name="android:layout_gravity">bottom|left</item>
    <item name="android:layout_margin">@dimen/common_layout_zero_dp</item>



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.

Online resources caching

To display the map some external resources are needed by the map renderer: map style and map tiles.

The map style itself (a .json file describing map layers display properties and rendering order) and assets needed by the style are bundled with the SDK library. Style assets include sprites (sets of icons) displayed on the map and fonts.

When the map viewer is focused at a particular spot, map tiles provided by the remote online server are needed to display the map. When a part of the map is displayed for the first time, the needed tiles are downloaded from the server.

Resources downloaded from the server are stored (cached) in an offline database for further use. The server communicates maximum tile resource lifetime by means of a "Cache-Control" HTTP header.

Expiration time is stored in the offline database together with the tile resource. If a tile resides in the cache it can be displayed even if an internet connection is not available.

When the object in the cache expires, the server is asked again about the object. If a newer version of the object is available, it is downloaded and the cache contents are refreshed. If the old resource is still valid, its lifetime is prolonged.

Cache size is limited to 50MB of disk space. When the limit is reached, the least recently used tile resources are discarded.

Map Layers

The Maps SDK uses JSON file (styles) defining the sources of data to be shown on the map and its appearance. Styles are compliant with the Map Styles Specification.


The layers property of a style is an array of all the layers the style defines. Each element of the array contains all the information needed to render a layer. Note that a single element of a map, such as a road, may consist of several layers. Among the properties of a layer, two are of particular interest in this context:

  • source - The name of the source of data for the layer; corresponds to a child of the sources property.

  • source-layer - The name of a layer in a vector tile source; corresponds to an element of a vector tile.


Sources are defined as properties of the sources root property of a style. The structure of a source depends on its type. The style used in the Maps SDK contains three types of source:

  • vector - vector map and traffic tiles

  • raster - raster map and traffic tiles

  • geojson - additional elements such as chevron, gps inaccuracy radius indicator, etc.

Source layers

The source layer property of a layer is mandatory for all layers of the vector type. It defines the element of a vector tile (also called a layer) which is the source of data for this layer.

As noted in the Layers section, there are elements of the map that consist of multiple layers. The layers that constitute such an element might refer to the same source layer. For instance - the visual representation of a minor local toll road comprises 11 layers - one for the main part, one for the outline, another one for a road that goes through a tunnel, etc.

Check the Map Display API documentation for a complete list of vector layer sources (layers in a vector tile) used in the SDK.

Custom style

You can change the appearance of the map by providing a JSON file (style) defining the sources of data to be shown on the map and its appearance. A style has to:

  • Include all mandatory layer sets (see Table 1).

  • Contain Maps SDK-specific tags.

  • More information about TomTom styles is available in the Map Styles Specification.

A basic style is provided as a part of the Custom Style Resources package.

Styles compliant with the Map Styles Specification can be edited using Map Styler. Before a style can be edited in Map Styler:

  • Service key placeholders have to be replaced with actual service keys.

  • All service keys included in the style must be valid for the Map Display API product.

  • Sprite and glyph locations have to be replaced by ones that can be reached by Map Styler. If service key is needed to access these resources, it must be included.

  • Maps SDK-specific tags have to be removed from tile source links or replaced with default values.

  • (Optional) Visibility of layers can be altered to your preferences.

All these changes, with the exception of layer visibility, have to be reverted before the modified style can be used with the SDK. Custom Style Resources contain a Python script - - which simplifies this process. Detailed usage instructions can be found in the following dedicated section.

Layer sets

The SDK uses the concept of a layer set to refer to a group of layers. A layer set consists of all layers using the same source. Layer sets listed in Table 1 are required for the SDK to function. If any of these layer sets are absent or do not meet the requirements mentioned below, they will be replaced with default layer sets created at runtime.

Table 1. Mandatory layer sets
Map view element Default source name Required layer type Required layer count Source type

Route polyline





Route start icon





Route end icon





GPS inaccuracy radius





Position indicator





Vehicle icon





Two layers for route polyline define the outline and fill styles. Two layers for chevron, GPS radius and position define the styles of two versions of associated objects - normal (active) and dimmed (inactive).

There is a number of layer sets that are important, but not strictly required. They are responsible for providing style and data sources for maps - vector and raster, traffic flow and incidents as well as hybrid overlay. These sets will not be replaced by default ones at runtime.

Source URIs for map layer sets have a fixed format - they contain placeholders for API keys and optional parameters. It is not recommended to change them.

Raster tile size

The SDK offers 256x256 px and 512x512 px raster tiles. By default, the larger tiles are used. The size of tiles can be modified by setting the tileSize parameter in the url of raster sources to either 256 or 512.


The script is distributed as a part of the Custom Style Resources bundle. It can be executed with one of two commands: 'mapstyler' and 'mapssdk'. When executed with the 'mapstyler' command, it replaces Maps SDK-specific elements of the base style (-b|--base parameter) with values provided in script’s parameters or in Info.plist or AndroiManifest.xml. When executed with the 'mapssdk' command, it reverts changes related to Maps SDK-specific elements while leaving user’s modification intact. Because of Map Styler requirement, API key contained in field "OnlineTraffic.key" of Info.plist or AndroidManifest.xml must be valid also for Map Display API product.

For the script to work properly, the same base file has to be used for both conversions.
Detailed usage instructions
python2 <common parameters> <command=mapstyler|mapssdk> <command-specific parameters>

# All parameters are required unless specified otherwise

common parameters:
  -w WDIR, --wdir WDIR  Working directory. Root of relative paths.
                        [optional, default = "."]
  -S, --silent          Silent mode. No messages will be printed.
  -b BASE, --base BASE  Path to the base for the new style.
  -o OUTPUT, --output OUTPUT
                        Path to the output file.

    mapstyler           Convert a base style so that it can be edited in
                        Map Styler.
    mapssdk             Convert a style edited in Map Styler so that it works
                        with your application using Maps SDK.

mapstyler parameters:
  -k KEYS, --keys KEYS  Path to Info.plist or AndroiManifest.xml.
  -s SPRITES, --sprites SPRITES
                        Online location of sprites.
  -g GLYPHS, --glyphs GLYPHS
                        Online location of glyphs.
  -v {all,none,intact,predefined}, --visibility {all,none,intact,predefined}
                        Change visibility of layers. 'intact' leaves the base
                        style's settings intact, 'predefined' makes vector
                        layers visible and all other layers invisible.
                        [optional, default = "predefined"]

mapssdk parameters:
  -e EDITED, --edited EDITED
                        Path to the style edited in Map Styler.
Sample workflow
  1. Upload glyphs and sprites to an online location accessible by Map Styler.

  2. Use to create a style that can be edited in Map Styler.

    python2 -b mapssdk-default-style.json -o my_style_prepared_for_mapstyler.json mapstyler -k path/to/app/AndroiManifest.xml -g -s
  3. Upload my_style_prepared_for_mapstyler.json to Map Styler.

  4. Edit the style in Map Styler.

  5. Export the style in Map Styler, saving it as my_style_exported_from_mapstyler.json.

  6. Use to prepare the style edited in Map Styler to for use with Maps SDK.

    python2 -b mapssdk-default-style.json -o my_style_prepared_for_sdk.json mapssdk -e my_style_exported_from_mapstyler.json

    == Migration guide

Use style from Style Merger

Starting with version 2.4.537, we are switching bundled-in styles and sprite, to using TomTom hosted styles and sprites. More information about the new approach is available in Map Initialization. Thanks to integration with Merged Style method provided by Map Display API you can generate and use one style for map and traffic display. The main benefits of TomTom hosted display resources are as following:

  • It makes application download size MB smaller in comparison to using bundled-in resources.

  • It allows you to get the newest look and feel of the map and traffic.

Maps SDK will work with the bundled-in style until June 2021 but we recommend to switch to using hosted assets sooner.

Until version 2.4.537, the style in the SDK has been included in the map package and consisted of layers from: Vector tiles, Traffic Flow, Traffic Incidents and Raster tiles. The approach of using a single style that contains multiple Traffic Flow tiles types was deprecated. After the deprecation period is over, it will not be possible to switch between Traffic Flow tiles types without reloading the style. Until deprecation is over in June 2021, the default map style which contains both raster and vector tiles is using SDK_BUNDLED, as a default value for the enum MapStyleSource.

Deprecated methods include UiSettings with all of its methods and TrafficSettings:

  • UiSettings:
    setMapLayersType(MapLayersType mapLayersType)
    setMapTilesType(MapTilesType mapTilesType)

  • TrafficSettings:
    turnOnVectorTrafficFlowTiles(TrafficFlowType.VectorTrafficFlowType trafficFlowTilesStyle)
    turnOnRasterTrafficFlowTiles(TrafficFlowType.RasterTrafficFlowType trafficFlowTilesStyle)

We encourage you to switch to the Merged Style method. It offers the following advantages to a proposed solution:

  • Each style has its own sprite sheet and is now fully independent.

  • A user can mix and match all sources of tiles in any manner as styles and sprite sheets are now merged on the server side. The selection of a particular style combination is done by providing custom Style Merger URL parameters.

  • It is easier to style traffic in the Map Styler as it can be easily loaded together with a map by using a merged version of the styles. However, the style from the Style Merger can only be used as a base for a custom style. Using this edited style and the Style Merger at the same time is not possible.

  • SDKs do not merge styles in runtime (e.g., it is required to have some hard-coded values to put traffic below the label layers in a map).

In case you have your own custom style that is not compliant with the TomTom sourcing names convention, you will use LayerSetConfiguration, which provides custom IDs for sources in the style.
LayerSetConfiguration should only be used with the MapStyleSource set to STYLE_MERGER.

Map initialization with the Style Merger endpoint using Merged Style functionality is described in section "Map properties". To the new functionality you need to implement a builder as described in the following example:
MapStyleSource is used to determine if the default and loaded style should support Style Merger. Setting it to STYLE_MERGER results in the default style only supporting vector tiles:


When MapStyleSource.STYLE_MERGER is selected, the method related to directly switching between raster and vector tiles will throw an exception. MapProperties can be also be declared in the XML by adding the following line:


to the snippet:

   tomtom:mapStyleSource="STYLE_MERGER" />

In case you have your own custom style that is not compliant with the TomTom sourcing names convention, you will use LayerSetConfiguration which provides custom IDs for sources in the style.

LayerSetConfiguration should be used only with the MapStyleSource set to STYLE_MERGER.

val layerSetConfiguration = LayerSetConfiguration.Builder()



        new LayerSetConfiguration.Builder()

Traffic flow tiles

IMPORTANT: The Maps SDK should be initialized with the style from Style Merger which only supports vector tiles and one type of the flow overlay. The approach of using a single style that contains multiple Traffic Flow tiles types was deprecated. After the deprecation period is over, it will not be possible to switch between Traffic Flow tiles types without reloading the style.

The Maps Display API provides support for the traffic flow overlay which can be displayed for both raster and vector tiles. The Style obtained from the Style Merger endpoint contains only one type of the Traffic Flow. To display other types of Traffic Flow it is required to reload the style to one which contains another Traffic Flow type.

The complete list of supported Traffic Flow types is listed below:

  1. absolute: Free-flow speed.

  2. relative (default): Speed relative to free-flow.

  3. relative-delay: Speed relative to free-flow, but only when different.

  4. reduced-sensitivity: Speed relative to free-flow, but with wider speed ranges.

Traffic incident tiles

Maintaining the currency of traffic incident tiles

IMPORTANT: The Maps SDK should be initialized with the style from Style Merger which only supports vector tiles. The approach of using a single style that contains both Raster and Vector tiles was deprecated. After the deprecation period is over, it will not be possible to switch between Raster and Vector Traffic Incidents without reloading the style.

Traffic incident data provided as map tiles by the Vector Incident Tiles and Raster Incident Tiles services is updated periodically to reflect the current state of traffic as closely as possible. It might happen that the traffic data changes between two requests to the service. In this situation, always requesting the most recent data may lead to inconsistencies in the visual representation of traffic. Adjacent tiles may show traffic in different states.

The traffic incident tile services provide a way to synchronize tiles between Requests. If the ID of a traffic model is supplied in a Request’s URL, the traffic model specified by that ID is used to fulfill the Request. The Traffic Incident Viewport service provides the ID of the most recent traffic model shared between all tiles within the provided viewport. The Maps SDK automatically synchronizes traffic incident tiles displayed on the map and maintains their currency by periodically requesting a traffic model ID for the current viewport.

The Maps SDK requests a current traffic model ID from the Traffic Incident Viewport service every 30 seconds as long as the visibility of at least one traffic incident layer is set to true. If the new ID and the current one are different, new traffic incident tiles are requested from the respective service. All regular charges apply.

Default style

Layer groups in the default style

IMPORTANT: The Maps SDK should be initialized with the style from Style Merger which only supports vector tiles. The approach of using a style that contains both raster and vector tiles was deprecated. After the deprecation period is over the default style will not contain raster layer groups.

In order to display raster tiles, you can check out our Map Tiles example.

The default style delivered with the SDK contains the following layer groups (background to foreground):

  1. Background: Color and pattern displayed in places where there is no other map data.

  2. Vector map: The baseline tile layer in vector format.

  3. Raster map: The baseline tile layer in raster format.

  4. Raster overlay for hybrid maps: Streets, labels, and icons on a transparent background.

  5. Traffic flow: Raster and vector traffic flow tile overlays.

  6. Traffic incidents: Raster and vector traffic incident tile overlays.

  7. Routes :Planned and alternative routes.

  8. Vector map labels and icons – Rendered on top of most other layers for better readability.

  9. GPS inaccuracy indicator - A circle indicating the GPS inaccuracy area.

  10. Position indicator - A static location marker.

  11. Chevron - An animated location marker.