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

Custom style

Custom style

Custom style

You can change the appearance of your map by providing a JSON file containing rendering properties of map elements. Such style file has to:

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

Styles compliant with Mapbox Style Specification can be edited using style editors like maputnik. Before a style can be edited in maputnik:

  • service key placeholders have to be replaced with actual service keys,

  • sprite and glyph locations have to be replaced by ones that can be reached by maputnik,

  • TomTom-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 a dedicated section below.

Layer sets

Layers tied to the same data source are treated by the SDK as a layer set. The ID (name) of the data source is used as the name of related layer set. Layer sets listed in Table 1 are required for the SDK to function. If any of these layer sets is absent or does not meet the requirements mentioned below it will be replaced with a default layer set created at runtime.

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

Active route polyline





Inactive route polyline





Route start icon





Route end symbol





Vehicle icon





GPS inaccuracy radius





Position indicator





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.

Table 2. Layer sets important for rendering elements of the map
Map view element Default source name

Vector map


Raster map


Traffic flow


Traffic incidents


Hybrid overlay


User-defined layer set

You can create your own layer sets to replace the default ones. If you use names different than the defaults listed in the tables above, you need to tell the SDK which map view element your custom layer set corresponds to. If names of the layer sets are not delivered, the SDK tries to reach layer sets by using default names.

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

Style API

When your custom style is ready, you can use it in your application in a number of ways:

  • provide a URI to a location accessible by your application in setStylePath(…​)

  • replace the default style:

    • create a data/style directory in your project’s root

    • rename your file to style.json and place it in data/style

    • copy glyph and sprite folders from framework to data/style

Sample use case: You want to display a night-themed map at night or while in a tunnel.

Even though online style locations are supported, glyphs and sprites have to be stored locally.


Basic style


Night custom style


The script is distributed as a part of the Cumstom Style Resources bundle. It can be executed with one of two commands: 'maputnik' and 'tomtom'. When executed with the 'maputnik' command, it replaces TomTom-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 'tomtom' command, it reverts changes related to TomTom-specific elements while leaving user’s modification intact.

For the script to work properly, the same base file has to be used for both conversions.
Detailed usage instructions
python2 <common parameters> <command=maputnik|tomtom> <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.

    maputnik            Convert a base style so that it can be edited in
    tomtom              Convert a style edited in maputnik so that it works
                        with your application using TomTom SDK.

maputnik 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"]

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

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

    python2 -b mapssdk-default-style.json -o my_style_prepared_for_maputnik.json maputnik -k path/to/app/AndroiManifest.xml -g -s
  3. Upload my_style_prepared_for_maputnik.json to maputnik.

  4. Edit the style in maputnik.

  5. Export the style in maputnik, saving it as my_style_exported_from_maputnik.json.

  6. Use to prepare the style edited in maputnik to for use with TomTom SDK.

    python2 -b mapssdk-default-style.json -o my_style_prepared_for_sdk.json tomtom -e my_style_exported_from_maputnik.json