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

Services quickstart

The Services bundle (@tomtom-org/maps-sdk/services) calls TomTom's location APIs and returns typed results, GeoJSON wherever the result has a geometry. It runs in browsers, Node.js and React Native, and needs no map.

Installing dependencies

npm install @tomtom-org/maps-sdk

Services needs @turf/turf, lodash-es and zod as peer dependencies; the project setup guide covers installing them with pnpm.

Setup

Set the API key once in the global configuration; every call reads it from there:

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

TomTomConfig.instance.put({ apiKey: 'YOUR_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.

Available services

Places, routes, reachable ranges, geometries and traffic come back as GeoJSON, ready for the map modules; getPOICategories, getPOICategoryCodes, evChargingStationsAvailability and getSearchSuggestions return plain objects. Every call takes the common request options: cancellation, validation, hooks, per-call overrides.

Places services

Places services: search, geocoding, place details, POI categories and EV charging. Results are places.

import {
    discoverPlaces,                 // free-form, category, in-area and along-route search
    geocode,                        // address → coordinates
    reverseGeocode,                 // coordinates → address
    getSearchSuggestions,           // search box: places, brands and categories
    getPlaceDetails,                // a place by its id
    getPOICategories,               // the POI category tree
    geometryData,                   // the outlines of areas such as cities and countries
    evChargingStationsAvailability, // live EV connector availability
} from '@tomtom-org/maps-sdk/services';

const results = await discoverPlaces({ query: 'restaurants', geoBias: { position: [4.9041, 52.3676] } });
const location = await geocode({ query: 'Dam Square, Amsterdam' });
const address = await reverseGeocode({ position: [4.9041, 52.3676] });

Routing services

Routing services: routes and reachable ranges (isochrones). Results are routes.

import {
    calculateRoute,           // routes between locations
    calculateReachableRanges, // reachable-range polygons (private preview)
} from '@tomtom-org/maps-sdk/services';

const routes = await calculateRoute({
    locations: [
        [4.9041, 52.3676], // Amsterdam
        [2.3522, 48.8566]  // Paris
    ]
});

Traffic services

Traffic incident details and traffic area analytics:

import { trafficAreaAnalytics, trafficIncidentDetails } from '@tomtom-org/maps-sdk/services';

const incidents = await trafficIncidentDetails({
    bbox: [4.728, 52.278, 5.08, 52.479] // [minLng, minLat, maxLng, maxLat]
});

Node.js usage

The services work the same in Node.js, where the API key stays off the client. The package ships ES modules only: import it from a .mjs file or a package with "type": "module", which also allows the top-level await below.

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

TomTomConfig.instance.put({ apiKey: process.env.TOMTOM_API_KEY });

const results = await discoverPlaces({
    query: 'coffee shops',
    geoBias: { position: [4.9041, 52.3676] }
});

The Node.js geocoding example runs this setup end to end.

Next steps