TomTom Maps SDK for JavaScript
This is the documentation of version 0.62.2. Go to the latest version, 1.0.0-rc.5.

About Maps SDK for JavaScript

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.

The map above is the default map example, and this is its code:

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

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

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

container is the id of the page element the map fills, so give that element a height.

Quickstart

  1. Get your TomTom API key:

Before you ship, decide where this key will live. A key used from the browser can be read by anyone who opens the page. A key used from Node.js cannot. See Where your API key runs for which case you are in and what to do about it, and TomTom's API key management best practices for key restrictions, rotation and monitoring.

  1. 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-sdk
  1. Start building:
npx skills add tomtom-international/maps-sdk-js --skill tomtom-maps-sdk-js

For more project setup details, see the Project Setup Guide.

For AI agents, project setup and the quickstarts are also published as Markdown: project setup, and the map, services and core quickstarts.

AI coding agent skill

The SDK ships a /tomtom-maps-sdk-js skill with SDK-specific knowledge for AI coding agents (Claude Code, Cursor, GitHub Copilot, Windsurf, and many more). Install it with the command above, then see AI coding with the SDK for the topics it covers and how to invoke them.

Overview

Maps SDK for JavaScript is a JavaScript/TypeScript library for building applications using TomTom map display and geolocation APIs.

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: the MapLibre map is fully exposed, so its API and plugin ecosystem work alongside the SDK.

Key features

Where can you run it?

Bundles

The Maps SDK is made up of three bundles:

Next steps