How the SDK works

The SDK is one npm package, @tomtom-org/maps-sdk, with three entry points. Map draws the map, Services calls TomTom's location APIs, and Core holds what both share. Use each alone or together.

The playground below uses only the Map bundle, with a TomTomMap configured once through Core.

The three bundles

• Map and Services never depend on each other. Both depend on Core, so Services runs on a server with no map, and Map draws your own data with no service.
• They meet through Core's GeoJSON types. A map module shows what a service returns unchanged, with no adapter in between.
• Everything is tree-shakable. Your bundle carries only the modules and services you import.

Data flow

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

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

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

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

1. TomTomConfig holds the API key and language once, for the map and every service call.
2. discoverPlaces merges its own parameters over that configuration, calls the API and resolves to a GeoJSON FeatureCollection of Place features.
3. PlacesModule.show takes that collection as it is and draws it on its own sources and layers.

Map

• TomTomMap wraps a MapLibre Map. It loads a TomTom style, applies the global configuration and exposes the MapLibre instance as map.mapLibreMap (when to use the SDK or MapLibre).
• Modules add everything else, each covering one area of the map. There are two kinds:
  • Style-owned modules, from get(map), cover what the style already draws, such as the base map, POIs, traffic and terrain. A map has one of each.
  • Data-owned modules, from create(map), show your data, such as places, routes, geometries and your own GeoJSON. Create as many as you need.
• Modules survive style switches. await map.setStyle(…) restores every module's data and settings on the new style (Map styles).
• Every setting is data. Each module's configuration has stable knob ids, set the same way on every module (Every setting as data). Map styling restyles the map at runtime.
• Events are typed per module. A click on a place pin gives you the Place you showed (User events).

Services

• Each API has one async function. Places covers search and geocoding. Routing covers route calculation and reachable ranges, and Traffic covers incident details and area analytics.
• The global configuration is the baseline. A call's own parameters win for that call only (Global configuration).
• Results are typed GeoJSON for places, routes, reachable ranges, geometries and traffic. The POI category and search-suggestion services return plain objects.
• Every call takes the same request options: validation, an AbortSignal and typed errors (Request options and errors).

The same calls run in Node.js, with no map. The Node.js reverse geocoding example runs this one:

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { reverseGeocode } from '@tomtom-org/maps-sdk/services';

TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });

const place = await reverseGeocode({ position: [5.72884, 52.33499] });
console.log(JSON.stringify(place, null, 4));

Core

• Global configuration: TomTomConfig.instance.put({ apiKey, language, … }), called once and read by the map and every service.
• Shared types: Place, Route and the traffic types, the shape both bundles agree on.
• Utilities that need no map: bounding boxes, coordinates, formatting and route progress.

Next steps

• Map only, with your own data: see the Map quickstart.
• Services only, in Node.js, a browser or React Native: see the Services quickstart.
• Both: see the examples gallery, where most apps combine them.
• Features beyond the three bundles, such as 3D landmarks or map effects: see How plugins work.