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

Migrate from previous versions - the Services library

Overview of the tutorial

This tutorial covers basic use cases to help you switch our services. For example, switching the Routing API or Search API services from our previous versions of the Maps SDK for Web to our new version. We will use code examples to explain the main differences between the SDKs. In the new SDK, services are not part of the map library. We now provide a separate library to only include services.

You can check how to migrate map displaying here: Migrate from previous versions - the Maps library

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

  • The SDK (Services library) can be downloaded from here: Downloads. Unzip it and save the contents 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
                    ├── services.min.js
                    ├── services-node.min.js
                    ├── services-web.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:

  • Add the following to the <head> element of your HTML document:

                        <script src='../sdk/services-web.min.js'></script>

    Maps and services use the same namespace and will automatically attach themselves to the tt object. Services will be accessible using


Displaying a route/directions

Here we have the code to display a route from point A to point B on the map.

Previous versions of the Maps SDK for Web

        .go().then(function(routeJson) {
            var route = tomtom.L.geoJson(routeJson, {
                style: {color: '#00d7ff', opacity: 0.6, weight: 6}
            map.fitBounds(route.getBounds(), {padding: [5, 5]});

Latest version of the Maps SDK for Web{
          key: '<your-api-key>',
          locations: '-122.510601,37.768014:-122.478468,37.769167'
        .then(function(response) {
            var geojson = response.toGeoJson();
                'id': 'route',
                'type': 'line',
                'source': {
                    'type': 'geojson',
                    'data': geojson
                'paint': {
                    'line-color': '#00d7ff',
                    'line-width': 8
            var bounds = new tt.LngLatBounds();
            geojson.features[0].geometry.coordinates.forEach(function(point) {
            map.fitBounds(bounds, {padding: 20});

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:


The following table lists the services from the previous SDK and their equivalent in the latest one.

Previous versions Current version
No equivalent

You are here