Migrating from Maps SDK for Web V6

TomTom deprecated Maps SDK for Web V6 on February 1, 2025, and withdrew its CDN endpoints on February 1, 2026. They answer 404 unless your contract runs past that date, and then only until it ends. V6 receives no further updates, security patches or bug fixes. The Maps SDK for JavaScript replaces it.

Why migrate

Feature comparison

Map display

Services

Developer experience

Plugins

Estimating migration effort

Use the table below to estimate the effort from the V6 features you use.

V6 API to new SDK

Find each V6 call you use and its replacement. Services come from @tomtom-org/maps-sdk/services and map classes from @tomtom-org/maps-sdk/map. None of them takes a key, because the global configuration holds it.

Map

Services

Responses come back as GeoJSON, so there is no toGeoJson(). Positions are [longitude, latitude] arrays throughout.

Step-by-step migration

Migrate incrementally, following only the sections your integration needs. The SDK works at two levels, which you can mix:

• At the high level, map modules draw what services return, with no layer management of your own.
• At the low level, map.mapLibreMap is the full MapLibre API. It is the most direct path for V6 code that called the map’s low-level methods (Using TomTom map with MapLibre directly). As you go, move each feature up to a module to get what the SDK adds.

Install the new SDK

Remove the legacy packages and CDN references, then install the new SDK:

1
# Remove legacy packages
2
npm uninstall @tomtom-international/web-sdk-maps @tomtom-international/web-sdk-services
3

4
# Install new SDK (peer dependencies installed automatically)
5
npm install @tomtom-org/maps-sdk

Also remove any V6 CDN <script> and <link> tags from your HTML. Your existing API key works with the new SDK.

Set up centralized configuration

The new SDK uses a singleton configuration pattern. Set your API key once at startup, and it applies to all maps and service calls.

Before (V6):

1
// API key passed to every call individually
2
var map = tt.map({ key: 'YOUR_API_KEY', container: 'map' });
3
tt.services.fuzzySearch({ key: 'YOUR_API_KEY', query: 'pizza' });

After:

1
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
2

3
// Set once at app startup — used by all maps and service calls
4
TomTomConfig.instance.put({
5
    apiKey: 'YOUR_API_KEY',
6
    language: 'en-GB',
7
});

You can still override the key per call or per map.

Migrate map initialization

Before (V6):

1
var map = tt.map({
2
    key: 'YOUR_API_KEY',
3
    container: 'map',
4
    center: [4.8156, 52.4414],
5
    zoom: 8,
6
});

After:

1
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
2

3
const map = new TomTomMap({
4
    mapLibre: {
5
        container: 'map',
6
        center: [4.8156, 52.4414],
7
        zoom: 8,
8
    },
9
});

Map options (center, zoom, bearing, pitch and all other MapLibre options) pass through unchanged under the mapLibre key.

Available styles:

V6’s separate trafficFlow, trafficIncidents and poi styles have no names of their own. You load the traffic parts with include (see Migrate traffic layers), and show, hide and filter the style’s own POIs with the POIs module.

1
const map = new TomTomMap({
2
    style: 'streetDark',
3
    mapLibre: { container: 'map' },
4
});

To switch style at runtime, call await map.setStyle('streetLight'). In V6, setStyle dropped every layer you had added. The SDK’s modules keep their data and settings and redraw on the new style (Map styles).

Migrate routing

Before (V6):

1
tt.services.calculateRoute({
2
    key: 'YOUR_API_KEY',
3
    locations: '4.89,52.37:4.88,52.36',
4
}).then(function(routeData) {
5
    var geojson = routeData.toGeoJson();
6
    map.addLayer({ /* ... */ });
7
});

After:

1
import { calculateRoute } from '@tomtom-org/maps-sdk/services';
2
import { RoutingModule } from '@tomtom-org/maps-sdk/map';
3

4
const routes = await calculateRoute({
5
    locations: [
6
        [4.89, 52.37],   // [longitude, latitude]
7
        [4.88, 52.36],
8
    ],
9
    travelMode: 'car',
10
});
11

12
// Pass directly to RoutingModule — no .toGeoJson() or manual layer setup needed
13
const routingModule = await RoutingModule.create(map);
14
await routingModule.showRoutes(routes);

The response is standard GeoJSON, with no .toGeoJson() conversion step. RoutingModule handles the layers, default styling, waypoint icons and traffic-section colouring, so the route renders with a single call and looks production-ready by default. To change the colour scheme, the line widths or the waypoint markers, configure the module.

To manage the map layers yourself, closer to how V6 worked, pass the GeoJSON response directly to map.mapLibreMap.addSource / addLayer:

1
// Low-level approach — use the MapLibre instance directly
2
map.mapLibreMap.addSource('route', { type: 'geojson', data: routes });
3
map.mapLibreMap.addLayer({ id: 'route-line', type: 'line', source: 'route', paint: { 'line-color': '#0080ff', 'line-width': 4 } });

setStyle drops layers added this way, and they get no SDK events. The Custom GeoJSON module takes the same layer specs and gives you both.

Migrate search and geocoding

Search and geocoding responses are standard GeoJSON, so you can pass them directly to the map. PlacesModule renders search results on the map as styled, interactive markers with minimal setup. For a data-only integration, the GeoJSON features work equally well with any MapLibre data source.

Before (V6):

1
tt.services.fuzzySearch({
2
    key: 'YOUR_API_KEY',
3
    query: 'restaurant',
4
    center: { lat: 52.37, lng: 4.89 },
5
}).then(function(results) { /* ... */ });

After:

1
import { discoverPlaces } from '@tomtom-org/maps-sdk/services';
2

3
const results = await discoverPlaces({
4
    query: 'restaurant',
5
    geoBias: { position: [4.89, 52.37] }, // [longitude, latitude]
6
});
7
// results is a typed GeoJSON FeatureCollection — access via results.features

For reverse geocoding:

Before (V6):

1
tt.services.reverseGeocode({
2
    key: 'YOUR_API_KEY',
3
    position: { lat: 52.37, lng: 4.89 },
4
}).then(response => { /* ... */ });

After:

1
import { reverseGeocode } from '@tomtom-org/maps-sdk/services';
2

3
const place = await reverseGeocode({ position: [4.89, 52.37] });
4
if (place.properties) {
5
    const address = place.properties.address;
6
}

Migrate traffic layers

TrafficFlowModule and TrafficIncidentsModule connect live TomTom traffic data to the map with pre-styled, interactive layers. Incident markers are styled and clickable out of the box. You can filter them by magnitude, category or road type without writing any rendering logic, and customise the modules for a different look.

Before (V6):

1
var map = tt.map({
2
    key: 'YOUR_API_KEY',
3
    container: 'map',
4
    stylesVisibility: { trafficFlow: true, trafficIncidents: true },
5
});
6
// Toggle later:
7
map.showTrafficFlow();
8
map.hideTrafficFlow();

After:

1
import { TomTomMap, TrafficFlowModule, TrafficIncidentsModule } from '@tomtom-org/maps-sdk/map';
2

3
// Include traffic layers when initializing the map style
4
const map = new TomTomMap({
5
    style: { type: 'standard', id: 'streetLight', include: ['trafficFlow', 'trafficIncidents'] },
6
    mapLibre: { container: 'map' },
7
});
8

9
const trafficFlow = await TrafficFlowModule.get(map, { visible: true });
10
const trafficIncidents = await TrafficIncidentsModule.get(map, { visible: true });
11

12
// Toggle visibility
13
trafficFlow.setVisible(false);
14
trafficIncidents.setVisible(true);
15

16
// Typed filtering — show only major and moderate incidents
17
trafficIncidents.updateConfig({
18
    filters: { magnitudes: { show: 'only', values: ['major', 'moderate'] } },
19
});

Migrate custom styling

In V6, you restyled the map by editing a style in Map Styler and loading its JSON. The new SDK loads standard styles only. Instead, the Styling Foundations module changes a style at runtime, and the change survives style switches.

1
import { setKnob, StylingFoundationsModule, stylingFoundationsKnobCatalogue } from '@tomtom-org/maps-sdk/map';
2

3
const styling = await StylingFoundationsModule.get(map);
4
setKnob(styling, stylingFoundationsKnobCatalogue, 'labels.sizeFactor', 1.2); // every base-map label 20% bigger
5
setKnob(styling, stylingFoundationsKnobCatalogue, 'roads.widthFactor', 0.8);  // thinner roads, hierarchy kept
6
styling.setMapColors({ land: '#f3f5f7', water: '#accbe2', roadMajor: '#a1b8ce' });

The map theme plugin derives those colours for you from your brand colours, your site’s CSS or an image. exportStyle saves the result as a style file.

Update CSS

Before (V6):

1
<link rel='stylesheet' href='https://api.tomtom.com/maps-sdk-for-web/cdn/6.x/.../maps.css'>

After:

The SDK applies the MapLibre CSS itself, from its own bundle. You only need this import to use the CSS of the MapLibre version you installed.

1
// In your JS/TS entry point
2
import 'maplibre-gl/dist/maplibre-gl.css';

Performance improvements

Bundle size

With modular ESM and tree-shaking enabled, you ship only the code you use.

Rendering engine

• MapLibre GL JS is actively maintained with performance improvements in every release
• Vector tile rendering runs on WebGL 2, which the map requires. In a browser without it, new TomTomMap throws a TomTomMapError with the code WEBGL_UNSUPPORTED
• Style part lazy loading loads layers on demand, so the map displays sooner
• Layer group visibility animation gives you smooth transitions

API response handling

• Native GeoJSON responses eliminate the serialisation/deserialisation overhead of V6’s .toGeoJson() conversion
• Typed responses are checked at compile time, so fewer errors reach runtime

Future-proof with Orbis Maps

The new SDK is the first to support TomTom Orbis Maps natively. Orbis Maps is TomTom’s map data platform, and it combines open data (OpenStreetMap) with TomTom’s proprietary data.

After migrating, your application gets every Orbis Maps improvement automatically.

Pricing and commercial impact

• Your API key stays the same. You don’t need a new key.
• Per-call pricing stays the same. Both SDKs call the same backend APIs, billed at the same rate whichever SDK made the call.
• Contract terms stay the same. Your existing agreement covers the new SDK, with no amendment.
• The free evaluation plan’s daily requests cover prototyping and testing the migration.
• Tailored enterprise plans, QPS limits and support levels carry over.

Using TomTom map with MapLibre directly

TomTomMap exposes the underlying MapLibre GL JS instance as map.mapLibreMap. Through it, the full MapLibre API (addSource, addLayer, on, queryRenderedFeatures and everything else) works exactly as in a standalone MapLibre project.

This is the most direct migration path for V6 code that calls TomTom’s tt.map methods directly. Replace tt.map(...) with new TomTomMap(...), swap the CSS import and then migrate the rest of the codebase incrementally. Each time a feature is ready for a high-level module, replace its manual layer code. Everything else keeps working unchanged through map.mapLibreMap.

1
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
2

3
const map = new TomTomMap({ mapLibre: { container: 'map' } });
4

5
map.mapLibreMap.on('load', () => {
6
    // Standard MapLibre API
7
    map.mapLibreMap.addSource('my-data', { type: 'geojson', data: myGeojson });
8
    map.mapLibreMap.addLayer({ id: 'my-layer', type: 'fill', source: 'my-data' });
9
});

Custom data visualisation, such as heatmaps, clustering, choropleth maps and deck.gl layers, works through map.mapLibreMap without any SDK-specific code. You can use the high-level modules and the raw MapLibre API on the same map instance at once. For GeoJSON layers, the Custom GeoJSON module takes the same layer specs and restores them after every style switch.

What’s not yet available

The new SDK is in Public Preview (0.x versions). Until 1.0, a minor release can carry a breaking change, and Upgrading to 1.0 lists each one. Some V6 capabilities are not yet available as first-party SDK features:

• SearchBox plugin - No drop-in replacement yet. Build on getSearchSuggestions(), starting from the search playground.
• Minimap / DrawingTools plugins - Use MapLibre community plugins, listed in awesome-maplibre.
• Turn-by-turn navigation UI - In-car navigation UI components are not yet available.
• Long-distance EV routing, vehicle consumption models and live EV charging availability - Not offered. Search returns EV stations with their static connectors and charging points.
• Matrix routing, structured geocoding, cross-street lookup, static map images, traffic flow segment data and incident viewport - No SDK function yet, so call those TomTom APIs over HTTP. For structured geocoding, pass the full address to geocode.
• CDN-only deployment - The new SDK requires a bundler (Vite, Webpack, etc.).

For GeoJSON data that no first-party module covers, use the Custom GeoJSON module. For anything else, map.mapLibreMap is the full MapLibre GL JS API.

Further reading

• How the SDK works — Architecture overview and key concepts
• Project setup — Installation and API key configuration
• Map quickstart — Your first map in minutes
• Services quickstart — Search and routing
• Core quickstart — What glues map and services together
• Map modules — Traffic, routing, places and more
• Map styles — Built-in themes and switching them
• Map styling — Restyle the map at runtime with knobs, brand colours and presets
• Terrain — Hillshade and 3D elevation
• Geopolitical views — One view for the map and every service call
• About MapLibre — What the SDK adds over raw MapLibre, and when to use map.mapLibreMap directly
• Traffic flow — Configuring live traffic flow layers
• Traffic incidents — Filtering and displaying incidents
• Routing guide — Route calculation parameters and options
• Search guide — Fuzzy, geometry and along-route search
• Search suggestions — Search-as-you-type over places, brands and categories
• Geocoding / Reverse geocoding
• Proxying your API calls — Keep the API key on your server
• Map theme, Map effects, Fly-over, Route dragging, Viewport places, Agent Toolkit — Plugins with no V6 counterpart
• AI coding with the SDK — The skill for your coding agent
• Upgrading to 1.0 — Breaking changes between 0.x releases
• API reference — Complete TypeDoc reference