TomTom Maps SDK for JavaScript

🎮 Examples | 📖 Documentation | 📋 API Reference | 🐙 GitHub

TomTom Maps SDK for JavaScript is a JavaScript library for building applications using TomTom location maps and services.

It leverages the power of MapLibre GL JS and GeoJSON to seamlessly integrate TomTom maps and services with convenient out-of-the-box support, while staying highly customizable and extensible.

⚠️ Public Preview Notice

We have released some capabilities in the Maps SDK under Public Preview to collect feedback from the community.

• While our goal is to keep the design of the interface stable, breaking changes will occur, particularly in the earlier versions.
• The versions will follow a 0.MAJOR.MINOR pattern for the time being.
• Stay tuned with our release CHANGELOG.md files.

🚀 Getting Started

npm i @tomtom-org/maps-sdk

🤖 AI Coding Agent Skill

Install the SDK skill for AI coding agents (Claude Code, Cursor, GitHub Copilot, Windsurf, and many more) to get SDK-specific assistance in your coding agent:

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

How it works

The SDK is split into three cooperating bundles — Map, Services, and Core. Services call TomTom APIs and return typed GeoJSON that Map modules consume directly. Core provides the shared config and types that bridge them. See How the SDK Works for a deeper dive.

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

// Configure once — all services and the map use this key
TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });

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

// Services return GeoJSON — map modules consume it directly
const places = await PlacesModule.get(map);
places.show(await search({ query: 'coffee' }));

const routing = await RoutingModule.get(map);
routing.showRoutes(await calculateRoute({ locations: [[4.9, 52.4], [13.4, 52.5]] }));

📚 Documentation & Examples

• Live Examples — try the SDK in your browser
• Getting Started — introduction and project setup
• API Reference — complete API documentation
• Release Notes — what's new and breaking changes

📦 Bundles

| Bundle | Import path | Platforms | |--------|-------------|-----------| | Map — interactive maps in styles, with POIs, traffic, places, routes and geometries | @tomtom-org/maps-sdk/map | web | | Services — GeoJSON services for places, routing, geocoding and more | @tomtom-org/maps-sdk/services | web, Node.js, React Native | | Core — shared config, types and utilities; no separate install needed | @tomtom-org/maps-sdk/core | web, Node.js, React Native |

📄 License

This repository uses a dual-licensing model.

SDK Packages and plugins - Proprietary License

The SDK packages (@tomtom-org/maps-sdk/* - core, services, map) and plugins (@tomtom-org/maps-sdk-plugin-*) are distributed under a proprietary license.

📜 LICENSE.txt - Full license terms

These packages require a TomTom API key and agreement to our terms of service.

Examples - Apache V2.0 License

All example code in the examples/ directory is open-source under the Apache V2.0 License.

📜 examples/LICENSE - Apache V2.0 License

The examples can be freely copied, modified, and used in your projects.

Source-Available Repository

This repository is source-available for transparency and learning. This is a read-only mirror - see CONTRIBUTING.md for how to provide feedback through issues and discussions.