Migrating from Maps SDK for Web V6

Maps SDK for Web V6 was deprecated on February 1, 2025, and its CDN endpoints were withdrawn on February 1, 2026: they answer 404 unless your contract runs past that date, and then only until it ends. The SDK receives no 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.

⚡ Migration carries zero additional cost. Your existing API key, contract, and pricing all remain the same. Every API call is billed identically whether it originates from V6 or the new SDK.

Why migrate

Feature comparison

Map display

Services

Developer experience

Plugins

Estimating migration effort

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

💡 For most integrations using map display + routing + traffic, expect 2–4 developer-days of migration work. The API patterns are intentionally similar, and the 110+ runnable examples make it easy to validate each feature.

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 takes a key, which the global configuration holds instead.

Map

Services

Responses are GeoJSON as returned, with no toGeoJson(), and positions are [longitude, latitude] arrays throughout.

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 MapLibre's full raw API. That escape hatch is also the most direct migration path for V6 code that called the map's low-level methods; move each feature up to a module as you go, for what the SDK adds.

Install the new SDK

Remove the legacy packages and CDN references. Install the new SDK:

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

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

Also remove any V6 CDN <script> and <link> tags from your HTML.

🔑 Your existing TomTom API key works with the new SDK. No new key or contract change is needed.

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):

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

After:

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

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

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

Migrate map initialization

Before (V6):

var map = tt.map({
    key: 'YOUR_API_KEY',
    container: 'map',
    center: [4.8156, 52.4414],
    zoom: 8,
});

After:

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

const map = new TomTomMap({
    mapLibre: {
        container: 'map',
        center: [4.8156, 52.4414],
        zoom: 8,
    },
});

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

Available styles:

V6's separate trafficFlow, trafficIncidents and poi styles have no names of their own: the traffic parts are loaded with include (see Migrate traffic layers), and the style's own POIs are shown, hidden and filtered with the POIs module.

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

Switching style at runtime is await map.setStyle('standardLight'). Unlike V6, where 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):

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

After:

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

const routes = await calculateRoute({
    locations: [
        [4.89, 52.37],   // [longitude, latitude]
        [4.88, 52.36],
    ],
    travelMode: 'car',
});

// Pass directly to RoutingModule — no .toGeoJson() or manual layer setup needed
const routingModule = await RoutingModule.create(map);
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:

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

Layers added this way are dropped by setStyle and get no SDK events. To keep your own layer specs with both, give them to the Custom GeoJSON module instead.

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):

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

After:

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

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

For reverse geocoding:

Before (V6):

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

After:

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

const place = await reverseGeocode({ position: [4.89, 52.37] });
const address = place.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):

var map = tt.map({
    key: 'YOUR_API_KEY',
    container: 'map',
    stylesVisibility: { trafficFlow: true, trafficIncidents: true },
});
// Toggle later:
map.showTrafficFlow();
map.hideTrafficFlow();

After:

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

// Include traffic layers when initializing the map style
const map = new TomTomMap({
    style: { type: 'standard', id: 'standardLight', include: ['trafficFlow', 'trafficIncidents'] },
    mapLibre: { container: 'map' },
});

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

// Toggle visibility
trafficFlow.setVisible(false);
trafficIncidents.setVisible(true);

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

Migrate custom styling

In V6, restyling the map meant editing a style in Map Styler and loading its JSON. Map Maker remains the tool for a style of your own, but most brand adjustments need none: the Styling module changes a standard style at runtime, and the change survives style switches.

import { StylingModule } from '@tomtom-org/maps-sdk/map';

const styling = await StylingModule.get(map);
styling.set('labels.sizeFactor', 1.2);      // every base-map label 20% bigger
styling.set('buildings.3d', true);          // extruded buildings
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, and exportStyle saves the result as a style file.

Update CSS

Before (V6):

<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.

// In your JS/TS entry point
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

• 110+ runnable examples with Sandpack — copy, modify, ship
• An AI coding-agent skill that gives your agent the SDK's patterns and APIs
• 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 calls 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.

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

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

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

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. 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, each listed in Upgrading to 1.0. 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
• Matrix routing, structured geocoding, cross-street lookup, static map images, traffic flow segment data and incident viewport — no SDK function yet; 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 no first-party module covers, use the Custom GeoJSON module; for anything else, 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
• 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
• EV Charging Availability — Live availability on your search results
• Long Distance EV Routing
• Proxying your API calls — Keep the API key on your server
• Map theme, Map effects, Fly-over, 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