Our map, yours to build: Maps SDK for Javascript now in general availability

TomTom Maps SDK for JavaScript is now generally available (GA). It’s one TypeScript library for TomTom maps, search, routing and traffic, built on MapLibre GL JS and ready for your AI coding agent.

A traffic control room, a site selection tool, a branded store finder: each one needs a map that looks right and dynamic location data that adds some function. With raw APIs, that takes a lot of glue code before anyone sees a thing. With the SDK, each layer becomes just a few typed calls.

In July, we made six Orbis APIs generally available. Today, the SDK that wraps them is joining them.

• One SDK for maps, search, routing and traffic, typed end to end and free to use with a TomTom API key.

• Less glue code. Service results go straight onto the map.

• A map you can grab. Drag a route to re-plan it live, light up 3D buildings and add your own three.js scene.

• Built for AI, from coding agents like Claude Code and Cursor to map agents your users can talk to.

Your first map in a minute

Install the package, add your API key and you have cafés and a traffic-aware route on a live map:

npm install @tomtom-org/maps-sdk

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { PlacesModule, RoutingModule, TomTomMap } from '@tomtom-org/maps-sdk/map';
import { calculateRoute, discoverPlaces } from '@tomtom-org/maps-sdk/services';

TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY', language: 'en-GB' });

const map = new TomTomMap({ mapLibre: { container: 'map', center: [4.9, 52.37], zoom: 12 } });

const places = await PlacesModule.create(map);
await places.show(await discoverPlaces({ query: 'coffee', geoBias: { position: [4.9, 52.37] } }));

const routing = await RoutingModule.create(map);
await routing.showRoutes(await calculateRoute({ locations: [[4.9, 52.37], [5.12, 52.09]] }));

That’s cafés in Amsterdam and a route to Utrecht, with no glue code in between: the search results and the route go straight onto the map. Run it in CodeSandbox, no install needed, or get a free API key to run it locally.

What is TomTom Maps SDK for JavaScript?

It’s a TypeScript library for building web apps with TomTom maps, search, routing and traffic, built on MapLibre GL JS. One npm package has three entry points:

• map renders the map and shows your data on it, in the browser.

• services calls TomTom’s location APIs and returns typed GeoJSON, in the browser, Node.js and React Native.

• core holds the shared configuration, types and geometry helpers.

Everything is tree-shakable, so you ship only what you import.

Plugins add more when you need it: Agent Toolkit, Route Dragging, Map Theme, Map Effects, Landmarks 3D, Fly-over and Viewport Places.

Start from over 130 runnable examples.

What’s new in 1.0

Drag anything

Users can now drag waypoints, route lines and place pins on any map module. The new Route Dragging plugin builds on it: grab a stop to move it, or pull the line to add one, and the route re-plans as the pointer moves.

import { RoutingModule } from '@tomtom-org/maps-sdk/map';
import { RouteDragging } from '@tomtom-org/maps-sdk-plugin-route-dragging';

const routing = await RoutingModule.create(map);
const dragging = new RouteDragging(routing);

await dragging.setWaypoints([
    [4.9041, 52.3676], // Amsterdam
    [5.1214, 52.0907], // Utrecht
]);

Try the route dragging example.

Your own 3D world that interacts

Hover a building and it lights up. Click it and it changes color. And with map.addCustomLayer, your own three.js or WebGL scene sits on the map, takes clicks and survives style switches. See the buildings interaction and three.js layer examples.

Routes that explain themselves

Routes now guide drivers to the main roads they can take, or provide alternative routes. For example avoid winding roads when passengers are prone to carsickness or sending a motorcyclist through the winding, scenic route. See the route curves example.

What you can build: a branded store finder

The tool: a page where customers find the nearest café and get directions, on a map that looks like the brand.

See it come together in the store locator example. Building something bigger? Explore the traffic control room and site selection examples.

What GA means

• Stable API. The SDK follows semantic versioning. Breaking changes only come in a major release.

• Clear errors. Every error has a code, like INVALID_CREDENTIALS, and error.canRetry tells you if trying again can help.

• Mistakes caught early. Request validation names any parameter a service doesn’t know, before the request goes out.

• Small bundles. Your app bundles only the SDK code its imports use.

Upgrading from a preview or release candidate? Most changes show up as type errors, so the compiler finds them for you.

The upgrade guide has the full list of changes from previous versions to help you with a smooth upgrade.

Why not just MapLibre GL JS and fetch?

• Results go straight onto the map. Services return typed GeoJSON. Map modules show it as is.

• Style changes keep your data. Switch from light to dark and your places, routes and layers stay.

• Typos fail at compile time. Every setting is typed, so a wrong value never reaches the map.

• MapLibre is still there. map.mapLibreMap gives you the raw map, so your existing code keeps working.

Rebranding the map takes one call:

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

const styling = await StylingFoundationsModule.get(map);
styling.setMapColors({ land: '#f3f5f7', water: '#accbe2', roadMajor: '#a1b8ce', label: '#364659' });

See Map colors and the accent.

Built for agents, and for coding with agents

Agent Toolkit: let users talk to your map

The Agent Toolkit (public preview) turns your map into an agent. Ask “find coffee along my route” or “how do these two routes differ?”, and the map answers.

• Ready-made tools for search, routing, traffic, styling and data visualization.

• Your model, your UI, built on the Vercel AI SDK, with room for your own tools and data.

• Safe by default. Code the model writes runs in a sandbox, or not at all.

Read the launch post for the full story.

Coding agents: build with Claude Code, Cursor and Copilot

More than a third of SDK questions to our docs assistant came from coding agents. So we built the SDK to help them get it right:

• Typed settings and strict validation turn a wrong guess into an error the agent fixes itself.

• A skill gives your agent SDK-specific guidance. Commit it so your whole team gets it.

• A feedback loop. The optional feedback skill lets your agent draft a report when the SDK gets in its way, and sends it only after you approve.

npx skills add tomtom-international/maps-sdk-js --skill tomtom-maps-sdk-js tomtom-maps-sdk-js-feedback

Agents help shape the SDK. Since we released the feedback skill, coding agents have filed more than 90 reports. More than half became fixes in a published release. A typical report got its first answer in about two hours.

Good to know before you install

Keep building

• Follow the Map quickstart or the Services quickstart. Both cover pnpm setup too.

• Copy from the examples gallery, from a store locator to a traffic agent.

• Install the skill so your coding agent knows the SDK from the first prompt.

What’s next: Share your feedback

Tell us what you need, or report what’s getting in your way:

• Bugs: open an issue on GitHub

• Ideas and questions: start a discussion

• Coding with an agent? The feedback skill lets your agent draft a report when the SDK gets in its way, and it sends only after you approve. Install it with:

npx skills add tomtom-international/maps-sdk-js --skill tomtom-maps-sdk-js-feedback

Editorial team

TomTom Blog