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

Services quickstart

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

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

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

Peer dependencies (installed automatically with above commands):

For more details, see the Project setup guide.

Setup

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

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

Places services

Search, geocoding, POIs, and EV charging:

import {
    discoverPlaces,     // free-form and category search
    geocode,            // address → coordinates
    reverseGeocode,     // coordinates → address
    getSearchSuggestions, // search box: places, brands and categories
    alongRouteSearch,   // search along a route geometry
    getPlaceDetails,    // look up a place by its id
    getPOICategories,   // POI category tree
    geometryData,       // administrative / geometry boundaries
    evChargingStationsAvailability, // live EV connector availability
} from '@tomtom-org/maps-sdk/services';

// Search for places
const results = await discoverPlaces({
    query: 'restaurants',
    geoBias: { position: [4.9041, 52.3676] }
});

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

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

Routing services

Route calculation and reachable areas (isochrones):

import {
    calculateRoute,           // point-to-point route calculation
    calculateReachableRanges, // isochrone / reachable-range polygons (private preview)
} from '@tomtom-org/maps-sdk/services';

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

Traffic services

Traffic incidents and area analytics:

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

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

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:

const { TomTomConfig } = require('@tomtom-org/maps-sdk/core');
const { discoverPlaces, calculateRoute } = require('@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] }
});

Next steps