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. V6 receives no further updates, security patches or bug fixes; the Maps SDK for JavaScript replaces it.

Migration carries no additional cost. Your API key, contract and per-call pricing stay the same (Pricing and commercial impact).

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 and traffic, expect 2–4 developer-days of migration work, with the 110+ runnable examples to check each feature against.

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

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

• High level: map modules draw what services return, with no layer management of your own.
• Low level: map.mapLibreMap is the full MapLibre API, the most direct path for V6 code that called the map's low-level methods (Using TomTom map with MapLibre directly). 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 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 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: { 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 Foundations module changes a standard style at runtime, and the change survives style switches.

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

const styling = await StylingFoundationsModule.get(map);
setKnob(styling, stylingFoundationsKnobCatalogue, 'labels.sizeFactor', 1.2); // every base-map label 20% bigger
setKnob(styling, stylingFoundationsKnobCatalogue, 'roads.widthFactor', 0.8);  // thinner roads, hierarchy kept
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

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

• Same API key: no new key is required.
• Same per-call pricing: both SDKs call the same backend APIs, billed at the same rate whichever SDK made the call.
• Same contract terms: your existing agreement covers the new SDK, with no amendment.
• Free evaluation: the free evaluation plan's daily requests cover prototyping and testing the migration.
• Enterprise plans: tailored plans, QPS limits and support levels carry over.

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