Developer

Migrate from version 4 - the Maps library

Overview of the tutorial

This tutorial covers some basic use cases to help you switch from version 4 of the 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.

Prerequisites

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

Displaying a map

1<!DOCTYPE html>
2<html class="use-all-space">
3  <head>
4    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
5    <meta charset="UTF-8" />
6    <title>My Map</title>
7    <meta
8      name="viewport"
9      content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no"
10    />
11    <!-- Replace version in the URL with desired library version -->
12    <link
13      rel="stylesheet"
14      type="text/css"
15      href="https://api.tomtom.com/maps-sdk-for-web/cdn/6.x/<version>/maps/maps.css"
16    />
17    <style>
18      #map {
19        width: 100vw;
20        height: 100vh;
21      }
22    </style>
23  </head>
24  <body>
25    <div id="map" class="map"></div>
26    <!-- Replace version in the URL with desired library version -->
27    <script src="https://api.tomtom.com/maps-sdk-for-web/cdn/6.x/<version>/maps/maps-web.min.js"></script>
28    <script>
29      tt.setProductInfo("<your-product-name>", "<your-product-version>")
30      tt.map({
31        key: "<your-tomtom-API-Key>",
32        container: "map",
33      })
34    </script>
35  </body>
36</html>

To locally run this example , 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.

Version 4 of the Maps SDK for Web

1var map = tomtom.map("map", {
2  key: "<your-api-key>",
3  basePath: "<your-tomtom-sdk-base-path>",
4  source: "vector",
5  center: [52.379189, 4.899431],
6  zoom: 12,
7})

Latest version of Maps SDK for Web

1var map = tt.map({
2  key: "<your-tomtom-API-key>",
3  container: "map",
4  center: [4.899431, 52.379189],
5  zoom: 12,
6})

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.

The preceding code example shows how to initialize a vector map with a default style. To see how to set another style, please take a look at the options.style parameter documentation.

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:

Version 4Current version
tomtom.key(key, [value])

You need to pass the API Key directly to the service.

   `tt.map({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:

   `map.setLanguage('en');`