TomTom LogoDocs
Products
Resources
Pricing
Sign in
Maps SDK for JavaScript
Introduction
Guides
Examples
API Reference

Services quickstart

VERSION 1.0.0-rc.3PUBLIC PREVIEW

The Services bundle (@tomtom-org/maps-sdk/services) calls TomTom’s location APIs and returns typed results, in GeoJSON when they have 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:

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


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

Before you ship, decide where this key will live. Anyone who opens the page can read a key used from the browser. A key used from Node.js stays private. Where your API key runs explains which case you are in and what to do. TomTom’s API key management best practices cover 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 and getSearchSuggestions return plain objects. Every call takes the common request options for cancellation, validation and per-call overrides.

Places services

Places services cover search, geocoding, place details, POI categories and EV charging stations. They return 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
} 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 calculate routes and reachable ranges (isochrones). They return 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 services cover 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, so import it from a .mjs file or a package with "type": "module". This 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