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

Creating a custom vector map style

This tutorial is only applicable for versions from 4.22.x onward.

Overview of the tutorial

This tutorial shows you how to create custom vector map style. In this tutorial you will do the following:

 

  • Modify a default TomTom style for vector maps with use of the Maputnik editor
  • Apply the newly created style

Prerequesites

  • API key
  • Npm and Node.js

We recommend you to have npm and Node.js already installed on your machine to quickly boot up a http server.

API keys

To get an API key:

 

Note - It is possible to have a single key(app) for all TomTom services, but you can also choose to have individual keys for the different services.

 

Step 1. Download our Maps SDK offline examples

Before you start, you need to download the latest version of our offline functional examples from here.

 

Step 2. Extract the examples

Create a new directory and extract the examples there.

For this tutorial, I created a directory called "examples". This is how it should look like after the extraction:

 

The contents of the "sdk" folder should look like this:

There are several directories and files, but we are only interested in the following ones:

  • glyphs - contains fonts used for rendering vector maps
  • sprites - contains images used for rendering vector maps
  • styles - contains json files with style definition

TomTom vector maps styles are compatible with Mapbox Styles Specification. This format defines rendered maps properties - fill colors, line styles and thickness, etc. To read more about this specification, please go to https://www.mapbox.com/mapbox-gl-js/style-spec/.
To be able to provide labels and additional images on the map (e.g. road shields) two more assets are required:

  • glyphs - these are fonts in a binary pbf format. They are transformed to speed up rendering process. To read more about it, please go to here. This is a rather advanced article.
  • sprites - they consist of two files:
    • image file - a png file containing concatenated images
    • index file - a json file describing content of an image file. 

Sprites might be provided in an additional form appropriate for high-DPI devices. In that case "@2x" suffix should be appended to the file names, e.g. "sprites@2x.png"
More about sprites can be found here.

Step 3. Run server with examples

This step is a prerequisite needed to configure the styles editor. In order to accomplish it, you need to have Node.js installed (this is out of the scope of this tutorial). Please, refer to (https://nodejs.org/en/download/), if you need further assistance with this task.

Open a console terminal and go to a directory created to host offline examples. Now, type in the following instruction:

npm install && npm start

After a while, you should see text similar to the one in this picture:

If you would like to know more about running offline examples, you may take a look at one of our tutorials: Running examples locally

Step 4. Upload styles

There are several ways to edit styles. You may do this manually in a text editor of your choice, but we prefer to use Maputnik - a visual map designer. You may find it here: https://maputnik.github.io/editor/

The first step is to upload a file containing a style definition to Maputnik. Click on the "Open" button.

Now, in a popup window, select the "Upload" button.

For this particular tutorial, we will edit the "basic_main.json" style. You may find it in the "styles" directory described in the"Extract the examples" step.

Step 5. Provide an API key in order to access data sources

One of the prerequisites for this tutorial is to obtain API key for an Online Map product. Now we will use it.

Click on the "Sources" button.

Next, replace "{key}" placeholder in each of the tile URLs with your API key.

Close the overlay to apply the changes by clicking on X in the top right corner.

Step 6. Update glyphs and sprites paths

In order to complete this step, we will use the http server with examples run in one of the previous steps. Click on the "Style Settings" button.

In a popup window, replace "Sprite URL" with

http://localhost:8080/sdk/sprites/sprite

and "Glyphs URL" with

http://localhost:8080/sdk/glyphs/{fontstack}/{range}.pbf

Close the overlay to apply the changes by clicking on X in the top right corner.

Step 7. Edit a style

Now, you should be able to see a map in the editor. From now on, you may edit all style properties and you will see an impact of your changes instantly. To give you a glimpse of possibilities, we will change the color of oceans. Click on an ocean on a map and select the "Ocean or sea" layer name from a popup.

From "Paint properties", select "Color".

Set a color of your choice. After this operation, oceans should be filled with a chosen color.

Step 8. Export a style

In order to download an edited style, click on the "Export" button.

In a popup window, choose the "Download" button.

Your new style should be available on your computer.

Step 9. Test your new style

Now, it's time to test your style. Go here and upload the modified style (click on the "Choose File" button). After a while you should achieve a following result:

Above steps allow you configure a default TomTom style for edition in Maputnik. If you are interested in the topic of vector tiles or the style customization, please find the following list of suggested further readings: