@tomtom-org/maps-sdk
v1.0.0
Published
TomTom maps, search, geocoding, routing, isochrones, EV and traffic for JavaScript — typed GeoJSON services and a MapLibre GL JS map.
Readme
TomTom Maps SDK for JavaScript
Examples | Documentation | API reference | Release notes | Earlier versions

Maps SDK for JavaScript is a JavaScript/TypeScript library for building applications with TomTom maps and location APIs.
It's built on MapLibre GL JS and GeoJSON. TomTom maps and services work together out of the box, and the MapLibre map stays fully exposed, so its API and plugin ecosystem work alongside the SDK.
From 1.0.0, the SDK follows semantic versioning under its versioning and support policy. The plugins stay in Public Preview until their own 1.0.0, or in Private Preview when their data needs an entitlement on your API key. The release notes list what changes in each release.
Quickstart
Get your TomTom API key at my.tomtom.com, following these instructions. Before you ship, decide where your API key runs.
Install the SDK:
# npm and Yarn install the peer dependencies for you npm install @tomtom-org/maps-sdk # pnpm does not, unless you ask it to echo "auto-install-peers=true" >> .npmrc && pnpm add @tomtom-org/maps-sdkUsing an AI coding agent? Install the SDK skill in your project root, for Claude Code, Cursor, GitHub Copilot, Windsurf and many more:
npx skills add tomtom-international/maps-sdk-js --skill tomtom-maps-sdk-js tomtom-maps-sdk-js-feedbackThe skill loads the SDK's patterns, coordinate conventions, service APIs and pitfalls into the agent's context, so the agent writes code against the real API instead of guessing it. Commit it so the whole team gets it. The optional
tomtom-maps-sdk-js-feedbackskill lets the agent report SDK problems it hits to TomTom, with your consent. AI coding with the SDK lists the topics it covers, how to invoke them and what a report holds.Start building. Services return GeoJSON, and map modules show it unchanged:
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]] }));Then follow the Map quickstart or the Services quickstart, or start from a runnable app in the examples gallery.
Requirements
- Node.js 22+ at install time, the minimum the package declares, whether or not you target the browser. Any package manager works: npm, pnpm or Yarn.
- A browser with WebGL for the Map bundle.
- A bundler such as Vite or webpack, because the SDK ships as ES modules. Under Vite,
TomTomMapsets up MapLibre's web worker on its own; Vite projects says when another bundler, such as webpack, needs it set up by hand. - Peer dependencies, installed by the commands above: MapLibre GL JS 6.15+, Turf 7, culori 4, Lodash 4 and Zod 4.
- TypeScript is optional: the SDK's own type definitions ship with the package. The GeoJSON types come from
@types/geojson, which you install yourself under pnpm (TypeScript support).
Project setup has the full requirements and the React, Vue and Node.js setups.
Bundles
One package, @tomtom-org/maps-sdk, carries three bundles:
| Bundle | Import path | Runs in | Holds |
| --- | --- | --- | --- |
| Map | @tomtom-org/maps-sdk/map | Browser | TomTomMap and its modules for places, routes, traffic and more |
| Services | @tomtom-org/maps-sdk/services | Browser, Node.js | One function per TomTom API, most returning GeoJSON |
| Core | @tomtom-org/maps-sdk/core | Anywhere | The shared configuration, types and utilities |
How the SDK works shows how the three fit together. Everything is tree-shakable: your bundle carries only the modules and services you import.
What you can build
Map
An interactive vector map in seven TomTom styles (streetLight, streetDark, streetLightDriving, streetDarkDriving, monoLight, monoDark and streetSatellite), switching between them at runtime, in the map language of your choice. Map modules draw on it:
- Places: search results as markers, with styling, clustering, and connections and entry points
- Routes: alternatives, waypoints, route sections for traffic, tolls and ferries, and route styling
- Geometries and reachable ranges: polygons, administrative boundaries and isochrones
- Custom GeoJSON: your own data, on layers that survive style switches and take part in the map's events
- Traffic: flow, incidents, planned ones included, incident details and area analytics
- Base map and POIs: show or hide layer groups such as 3D buildings and road shields, and filter the base map's points of interest
- Terrain: hillshade relief with its own light and colours, and 3D elevation
- Events: click, hover and context-menu events on every module, and module events such as
config-change
Map styling restyles the loaded map through semantic knobs instead of layer ids:
- Every setting as data: each module lists its settings in a knob catalogue, and
setKnob,getKnobandresetKnobset one by its id, validated, on any module. - Map-wide sizes and colours: label, icon and road sizes, and the ten map colours and the accent that routes, geometries and pins take.
- Presets:
applyMapPresetsets a whole look in one call. - Globe and sky: globe projection, sky and horizon.
- Geopolitical views: disputed borders and territories as one country sees them, on the map and in search.
Services
Typed GeoJSON from the TomTom APIs, with or without a map:
- Search:
discoverPlaces, search suggestions, place details and POI categories - Geocoding and reverse geocoding:
geocode,geocodeOneandreverseGeocode - Routing:
calculateRoute, with alternatives, guidance and vehicle restrictions - Reachable ranges: isochrones by time or distance budget, in Private Preview
- Traffic: incident details and area analytics
- Geometry data: administrative boundaries for a search result
- Request options and errors: request validation, cancellation and deadlines, and errors that name what went wrong with an
SDKErrorCode
Plugins
Separate packages, each declaring the SDK as a peer dependency:
| Plugin | What it does | | --- | --- | | Agent Toolkit | Lets your users plan routes, search places and restyle the map in natural language, with the LLM and chat UI of your choice | | Map Theme | Themes the map from a brand's swatches, your page's CSS, a logo or a photo | | Map Effects | Post-processing such as bloom, depth of field, colour grading and vignette, on any style | | Fly-over | A camera that flies along a route, framing the junctions ahead | | Route dragging | Lets your users edit a route by dragging its stops and its line, re-planned as they drag | | Viewport places | Keeps search results for the visible map area on the map as it moves | | Landmarks 3D | Detailed 3D models of recognizable buildings, in Private Preview, the base map's buildings in 3D with windows, lights and shadows, and textured water, ground and roads with 3D trees |
Coming from MapLibre GL JS
The map is a MapLibre map. TomTomMap wraps a MapLibre Map and keeps it reachable as map.mapLibreMap, so the MapLibre code, controls and plugins you already have keep working:
import { NavigationControl } from 'maplibre-gl';
map.mapLibreMap.addControl(new NavigationControl(), 'top-right');
map.mapLibreMap.on('moveend', () => console.log(map.mapLibreMap.getCenter()));Where the SDK has a feature for the job, prefer it. It survives style switches and style releases, and its events coordinate across modules. About MapLibre says which to use when.
Security and privacy
- Where your API key runs: anyone who opens the page can read a key used from the browser, but not one used from Node.js.
- Proxying your API calls: keep the key on your server by routing the SDK's requests through your own proxy, then harden that proxy.
- What the SDK sends, and where: the data your users' browsers send to TomTom, for your privacy notice.
- Reporting a vulnerability: report it privately, never in a public issue. When we fix one, we publish a GitHub security advisory and deprecate the affected versions on npm.
Resources for AI agents
Besides the coding skill, these entry points serve agents and the people configuring them:
- Bundled
.d.tsdeclarations: the API surface an editor and an agent complete against. - Markdown pages: project setup, and the map, services and core quickstarts, published for agents to read.
- Context7 index: this repository, indexed for agents using the Context7 MCP server.
examples/: over 110 runnable apps, the best code to copy from.
AI and the SDK covers both the coding skill and the Agent Toolkit, for putting an LLM in front of your users.
Documentation
- Introduction and project setup
- Guides, starting with how the SDK works
- Examples, live in your browser with their code
- API reference, every exported symbol with its signature and types
- Release notes and the changelog
- Migrating from V6, for apps on the TomTom Maps SDK for Web V6
License
This repository uses a dual-licensing model:
- SDK packages and plugins:
@tomtom-org/maps-sdk(core, services, map) and the@tomtom-org/maps-sdk-plugin-*packages are distributed under a proprietary license, in LICENSE.txt. They require a TomTom API key and agreement to our terms of service. - Examples: the code in
examples/is open source under the Apache 2.0 license, in examples/LICENSE. Copy, modify and use it in your projects.
The GitHub repository carries the examples, the changelogs and the AI coding skills. The SDK's sources aren't published. It's a read-only mirror, so report bugs in its issues and ask questions in its discussions.
