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

Migrate from previous versions - the Maps library

Overview of the tutorial

This tutorial covers some basic use cases to help you switch from our previous versions of Maps SDK for Web to the latest one as quickly as possible. We will use code examples to explain the main differences between the SDKs.

If you are just interested in migrating services you can refer to the migration tutorial for services.

To start using the latest version of TomTom Maps SDK for Web you need the following:

  • The Maps library can be downloaded from here: Downloads. Unzip it and save it in a folder. This tutorial assumes your folder is named ‘sdk’. If you choose another name, remember to change the provided paths to match it.

    Check out the current file structure

              └── sdk-tutorial
                  └── sdk
                      ├── LICENSE.txt
                      ├── glyphs
                      ├── sprites
                      ├── styles
                      ├── css-styles
                      ├── maps.css
                      ├── maps-web.min.js
                      ├── maps.min.js
  • API Key

    Create your API Key now

    To create a new API Key you need to first register on the portal. Once you are logged in there are only two steps remaining:

    Create a new application in your Dashboard:

    Choose all the APIs:

    All set up. You can now click on your newly created app and copy your API Key:

Displaying a map

      <!DOCTYPE html>
      <html class='use-all-space'>
          <meta http-equiv='X-UA-Compatible' content='IE=Edge' />
          <meta charset='UTF-8'>
          <title>My Map</title>
          <meta name='viewport'
          <link rel='stylesheet' type='text/css' href='../sdk/maps.css'/>
             #map {
                 width: 100vw;
                 height: 100vh;
          <div id='map' class='map'></div>
          <script src='../sdk/maps-web.min.js'></script>
          tt.setProductInfo('<your-product-name>', '<your-product-version>');
                  key: '<your-tomtom-API-Key>',
                  container: 'map',
                  style: 'tomtom://vector/1/basic-main'

To run this example locally, save the preceding code in a HTML file. Replace ‘<your-api-key>‘ with the API Key you obtained as shown in the Prerequisites section.

Also replace the basePath with the location of the SDK, assuming that you have saved it next to the file above, the basePath will be './sdk'.

To see the result simply open your HTML file in a browser. If there is any problem you can check the log in developer tools.

Initializing a map

The following code initializes a map using a defined center point and zoom level. In this section we compare the difference between both SDKs.

Previous versions of the Maps SDK for Web

      var map ='map', {
          key: '<your-api-key>',
          basePath: '<your-tomtom-sdk-base-path>',
          source: 'vector',

          center: [52.379189, 4.899431],
          zoom: 12

Latest version of Maps SDK for Web

    var map ={
            key: '<your-tomtom-API-key>',
            container: 'map',
            style: 'tomtom://vector/1/basic-main',
            center: [4.899431, 52.379189],
            zoom: 12

The code for both is similar:

  • Both map methods return a reference to the map.
  • Both use ‘center’ and ‘zoom’ as properties.

Both require the ID of an element to render the map (in this example 'map'), but now you have to pass it in a 'container' property.

Note that the tomtom namespace was changed to tt in the new SDK.

The new versions of our SDK use the longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON. You will have to change the order of those in all of the parts of your application where the coordinates are passed as an array.

Differences in APIs

Here is an overview of some of the most important updates within our top-level namespace.

Common factory functions renamed

Some of the common functions changed. Here are some examples:

Previous versions Current version
tomtom.key(key, [value]) You need to pass the API Key directly to the service.

    {key: API-KEY, ...});
tomtom.localeService() You need to pass the language directly to the service. For the map, you can also change the language after initialization by doing:


You are here