Migrating from Maps SDK for Web V6

Maps SDK for Web V6 was deprecated on February 1, 2025. Its CDN endpoints are being withdrawn, and the SDK will not receive further updates, security patches, or bug fixes. The new Maps SDK for JavaScript is TomTom’s strategic investment for web developers — built from the ground up with modern standards and designed to grow with your application.

Why migrate

Feature comparison

Map display

Services

Developer experience

Estimating migration effort

Every integration is different. Use the table below to estimate effort based on which V6 features you currently use.

Step-by-step migration

You can migrate incrementally. Tackle only the sections relevant to your integration.

The new SDK operates at two levels — and you can mix them freely.

• At the high level, map modules and services are tightly integrated: a route calculation, a place search, or a traffic query can flow directly into the map with production-quality visualization in just a few lines — no manual layer management, no custom styling boilerplate.
• At the low level, the underlying MapLibre GL JS instance is always accessible via map.mapLibreMap, giving you the same raw API that MapLibre (and previously Mapbox GL JS) exposed. That escape hatch is also the most direct migration path for V6 code that relied on Mapbox GL-like primitives.

Install the new SDK

Remove the legacy packages and CDN references. 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.

Set up centralized configuration

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

Before (V6):

1
// API key passed to every call individually
2
var map = tt.map({ key: 'YOUR_KEY', container: 'map' });
3
tt.services.fuzzySearch({ key: 'YOUR_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_KEY',
6
    language: 'en-GB',
7
});

You can still override the key per-call or per-map instance when needed.

Migrate map initialization

Before (V6):

1
var map = tt.map({
2
    key: 'YOUR_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 ) are passed through unchanged under the mapLibre key.

Available styles :

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

Migrate routing

Before (V6):

1
tt.services.calculateRoute({
2
    key: 'YOUR_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.get(map);
14
await routingModule.showRoutes(routes);

The response is standard GeoJSON. No .toGeoJson() conversion step. RoutingModule handles all layer management, default styling, waypoint icons, and traffic-section coloring automatically — the route renders on the map with a single call and looks production-ready by default. If you need a different color scheme, custom line widths, or your own waypoint markers, the module exposes configuration options for each.

If you prefer to manage the map layers yourself (closer to how V6 worked), the GeoJSON response passes 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 } });

Migrate search and geocoding

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

Before (V6):

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

After:

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

3
const results = await search({
4
    query: 'restaurant',
5
    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_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 result = await reverseGeocode({ position: [4.89, 52.37] });
4
const address = result.features[0]?.properties?.address;

Migrate traffic layers

Traffic is one of the areas where the tight map + services integration pays off most visibly. TrafficFlowModule and TrafficIncidentsModule connect the live TomTom traffic data to the map with pre-styled, interactive layers. Incident markers are clickable and richly styled out of the box; you can filter by magnitude, category, or road type without writing any rendering logic. The modules are also directly customizable if you need a different visual treatment.

Before (V6):

1
var map = tt.map({
2
    key: 'YOUR_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: 'standardLight', 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.filter({
18
    any: [{
19
        magnitudes: { show: 'only', values: ['major', 'moderate'] },
20
    }],
21
});

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 automatically downloads the correct MapLibre CSS version. You only need this import if you want to pin a specific version or override MapLibre styles.

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

Performance improvements

Bundle size

The modular ESM architecture means you only ship the code you use. With tree-shaking enabled:

Rendering engine

• MapLibre GL JS is actively maintained with performance improvements in every release
• Vector tile rendering leverages WebGL 2 on supported browsers
• Style part lazy loading enables faster initial map display by loading layers on demand
• Layer group visibility animation support for smooth UX transitions

API response handling

• Native GeoJSON responses eliminate the serialisation/deserialisation overhead of V6’s .toGeoJson() conversion
• Typed responses enable compile-time validation, reducing runtime errors

Developer velocity

• 54 runnable examples with Sandpack — copy, modify, ship
• Full TypeScript IntelliSense means less time reading docs, more time coding
• Centralised configuration eliminates the “forgot the API key” class of bugs

Future-proof with Orbis Maps

The new SDK is the first to offer native support for TomTom Orbis Maps — the next-generation map data platform that combines open data (OpenStreetMap) with TomTom’s proprietary data assets.

Migrating to the new SDK positions your application to benefit from every Orbis Maps improvement automatically.

Pricing and commercial impact

Migration to the new SDK has zero pricing impact. Your existing contract, API key, and billing terms remain unchanged.

• Same API key — your existing TomTom API key works with the new SDK. No new key is required.
• Same per-call pricing — every API call (map tiles, routing, search, traffic) is billed at the same rate regardless of which SDK initiated the call. Both SDKs call the same backend APIs.
• Same contract terms — your existing agreement covers the new SDK. No contract amendment or renegotiation is needed.
• Free evaluation — TomTom’s free evaluation plan provides enough daily API requests to prototype and test your full migration.
• Enterprise plans — enterprise customers retain their tailored plans, QPS limits, and support levels through migration.

Migration is a code change, not a commercial event.

Using TomTom map with MapLibre directly

TomTomMap exposes the underlying MapLibre GL JS instance via map.mapLibreMap. Once you have that reference, the full MapLibre API is available — addSource, addLayer, on, queryRenderedFeatures, and everything else — exactly as it works in a standalone MapLibre project.

This is the most direct migration path for V6 code that already calls Mapbox GL JS (or TomTom’s tt.map) methods directly. You can replace tt.map(...) with new TomTomMap(...), swap the CSS import, and then address the rest of the codebase incrementally: each time a feature is ready to adopt a high-level module, replace the manual layer code; everything else keeps working unchanged via 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 — identical to Mapbox GL JS
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 visualization — heatmaps, clustering, choropleth maps, deck.gl layers — all work through map.mapLibreMap without any SDK-specific code. The high-level modules and the raw MapLibre API coexist on the same map instance, so you can use both at once.

What’s not yet available

The new SDK is in Public Preview (0.x versions). Some V6 capabilities are not yet available as first-party SDK features:

• SearchBox plugin — no drop-in replacement yet; use the autocomplete search example as a starting point
• Minimap / DrawingTools plugins — use MapLibre community plugins (maplibre-gl-minimap, mapbox-gl-draw with MapLibre)
• Turn-by-turn navigation UI — in-car navigation UI components are not yet available
• CDN-only deployment — the new SDK requires a bundler (Vite, Webpack, etc.)

For any visualization not yet covered by a first-party module, map.mapLibreMap gives you the full MapLibre GL JS API as a fallback — see the section above.

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 custom styles
• About MapLibre — Community plugins and direct MapLibre access via map.mapLibreMap
• Traffic flow — Configuring live traffic flow layers
• Traffic incidents — Filtering and displaying incidents
• Routing guide — Route calculation parameters and options
• Search guide — Fuzzy search and autocomplete
• Geocoding / Reverse geocoding
• EV Charging Availability — New in this SDK
• Long Distance EV Routing
• API reference — Complete TypeDoc reference