Services quickstart

VERSION 0.51.5 PUBLIC PREVIEW

The Services bundle provides a comprehensive set of GeoJSON-based functions for accessing TomTom’s location APIs. These services can be used in any JavaScript-based application, from web browsers to Node.js servers.

Installing dependencies

1
# npm or Yarn - automatic peer dependency installation
2
npm install @tomtom-org/maps-sdk
3

4
# pnpm - enable auto-install-peers for easiest setup
5
echo "auto-install-peers=true" >> .npmrc
6
pnpm install @tomtom-org/maps-sdk

Peer dependencies (installed automatically with above commands):

lodash-es (v4) - Utility functions
zod (v4) - Schema validation

For more details, see the Project setup guide.

Setup

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

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

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

All services are imported from @tomtom-org/maps-sdk/services and return GeoJSON.

Places services

Search, geocoding, POIs, and EV charging:

1
import {
2
    search,             // free-form and category search
3
    geocode,            // address → coordinates
4
    reverseGeocode,     // coordinates → address
5
    autocompleteSearch, // type-ahead suggestions
6
    alongRouteSearch,   // search along a route geometry
7
    explorationSearch,  // browse POIs by category
8
    placeById,          // look up a place by its id
9
    getPOICategories,   // POI category tree
10
    geometryData,       // administrative / geometry boundaries
11
    evChargingStationsAvailability, // live EV connector availability
12
} from '@tomtom-org/maps-sdk/services';
13

14
// Search for places
15
const results = await search({
16
    query: 'restaurants',
17
    position: [4.9041, 52.3676]
18
});
19

20
// Geocode address
21
const location = await geocode({
22
    query: 'Dam Square, Amsterdam'
23
});
24

25
// Reverse geocode coordinates
26
const address = await reverseGeocode({
27
    position: [4.9041, 52.3676]
28
});

Routing services

Route calculation and reachable areas (isochrones):

1
import {
2
    calculateRoute,           // point-to-point route calculation
3
    calculateReachableRanges, // isochrone / reachable-range polygons
4
} from '@tomtom-org/maps-sdk/services';
5

6
const route = await calculateRoute({
7
    locations: [
8
        [4.9041, 52.3676], // Amsterdam
9
        [2.3522, 48.8566]  // Paris
10
    ]
11
});

Traffic services

Traffic incidents and area analytics:

1
import {
2
    trafficIncidentDetails, // incidents within a bounding box
3
    trafficAreaAnalytics,   // aggregated traffic statistics for an area
4
} from '@tomtom-org/maps-sdk/services';
5

6
const incidents = await trafficIncidentDetails({
7
    bbox: [4.728, 52.278, 5.08, 52.479] // [minLon, minLat, maxLon, maxLat]
8
});

Node.js usage

The services work identically in Node.js environments. Running them server-side also keeps your API key off the client, so read it from the environment rather than hardcoding it:

1
const { TomTomConfig } = require('@tomtom-org/maps-sdk/core');
2
const { search, calculateRoute } = require('@tomtom-org/maps-sdk/services');
3

4
TomTomConfig.instance.put({
5
    apiKey: process.env.TOMTOM_API_KEY
6
});
7

8
const results = await search({
9
    query: 'coffee shops',
10
    position: [4.9041, 52.3676]
11
});

Next steps

Places Services - Search, geocoding, POIs, EV charging
Routing Services - Route calculation and reachable ranges
Traffic Services - Incident details and area analytics
Customizing Services - Configuration options
Where your API key runs - Node.js keeps your key private; the browser does not. Which case you are in, and what to do