Global configuration

The Maps SDK keeps a single, application-wide set of configuration values — your API key, language, base URL, display units, and retry behavior — in one place. Setting these once means every service call and map module reuses them, so you don’t have to pass an API key (or any other shared option) into each individual request.

This guide explains how that global configuration works, what each option does, and how global values interact with the per-request options you pass to services.

The TomTomConfig singleton

Global configuration is managed by the TomTomConfig singleton, exported from the Core bundle. Because it is a singleton, there is exactly one configuration shared across your entire application — accessed through TomTomConfig.instance.

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

3
TomTomConfig.instance.put({
4
    apiKey: 'YOUR_API_KEY_HERE',
5
    language: 'en-GB'
6
});

Set your configuration once during application startup, before creating a map or calling any service. From then on, every SDK feature reads from this shared configuration automatically.

The three methods

TomTomConfig.instance exposes three methods:

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

3
// Merge values into the current configuration
4
TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY_HERE' });
5

6
// Read the current configuration
7
const config = TomTomConfig.instance.get();
8

9
// Restore the initial defaults
10
TomTomConfig.instance.reset();

• put(config) — merges the given values into the current configuration. New values override existing ones; keys you omit are left untouched.
• get() — returns the current configuration object.
• reset() — clears all custom values and restores the defaults. Note that the default API key is an empty string, so you must set a new API key after resetting.

put performs a shallow merge

put merges at the top level only. Nested objects — such as displayUnits and retry — are replaced entirely, not deep-merged. Calling put twice with different nested keys does not combine them:

1
TomTomConfig.instance.put({
2
    displayUnits: { distance: { type: 'metric' } }
3
});
4

5
// This REPLACES displayUnits — the distance setting above is now lost
6
TomTomConfig.instance.put({
7
    displayUnits: { time: { hours: 'hrs' } }
8
});

To change one nested field while preserving the rest, include the full nested object in a single call:

1
TomTomConfig.instance.put({
2
    displayUnits: {
3
        distance: { type: 'metric' },
4
        time: { hours: 'hrs' }
5
    }
6
});

Configuration options

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

3
TomTomConfig.instance.put({
4
    apiKey: 'YOUR_API_KEY_HERE',
5
    apiVersion: 1,
6
    commonBaseURL: 'https://api.tomtom.com',
7
    language: 'en-GB',
8
    trackingId: '9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1',
9
    displayUnits: {
10
        distance: { type: 'metric' },
11
        time: { hours: 'hrs', minutes: 'mins' }
12
    },
13
    retry: {
14
        initialWaitMs: 0.447,
15
        backoffFactor: 1.618,
16
        timeoutMs: 40000
17
    }
18
});

apiKey

Your TomTom API key, used to authenticate every request. Required for all SDK features. Obtain one from my.tomtom.com.

apiVersion

The API version for service endpoints. Defaults to 1. Each service may default to its own version and can override this value, so consult the specific service documentation when in doubt.

commonBaseURL

The base URL for all TomTom API services. Defaults to https://api.tomtom.com. Individual services can override this with their own base URLs. You typically only change it for testing or enterprise deployments — for example, to route traffic through a proxy.

language

An IETF language code (case-insensitive) applied to search results, routing instructions, and map labels. When omitted, the SDK uses NGT (Neutral Ground Truth) — the local language for each location.

See the supported-language lists for Search and Routing.

trackingId

An optional request identifier for tracing and support. It must match the pattern ^[a-zA-Z0-9-]{1,100}$; a UUID is the recommended format. When set, it is included in the Tracking-ID response header. This is solely for support purposes and does not involve user tracking.

displayUnits

Custom unit labels and unit system for distance and time. These are applied by the formatDistance and formatDuration utilities used throughout the SDK. If not provided, default labels are used.

1
TomTomConfig.instance.put({
2
    displayUnits: {
3
        distance: {
4
            type: 'imperial',  // 'metric' or 'imperial'
5
            miles: 'miles',
6
            feet: 'ft'
7
        },
8
        time: {
9
            hours: 'hrs',
10
            minutes: 'mins'
11
        }
12
    }
13
});

See the Formatting utilities guide for how these labels are used.

retry

Controls automatic retry behavior when a service request receives a rate-limited (429) response. When a 429 is returned, the SDK retries automatically using exponential backoff, respecting the API’s Retry-After header when present.

1
TomTomConfig.instance.put({
2
    retry: {
3
        initialWaitMs: 0.447,   // base delay before the first retry
4
        backoffFactor: 1.618,   // multiplier applied after each retry
5
        timeoutMs: 40000        // give up once total retry time would exceed this
6
    }
7
});

• initialWaitMs — base delay (in milliseconds) before the first retry, used when no Retry-After header is present. Defaults to 0.447.
• backoffFactor — multiplier applied to the wait time after each subsequent retry. Defaults to 1.618.
• timeoutMs — maximum total time to spend retrying, measured from the first request. If the next wait would exceed it, the 429 error is returned to the caller. Defaults to 40000.

How global and per-request configuration combine

Global configuration is a baseline. When you call a service, the SDK merges the global configuration with the options you pass to that specific call — and the per-request options take precedence.

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

4
TomTomConfig.instance.put({
5
    apiKey: 'YOUR_API_KEY_HERE',
6
    language: 'en-GB'
7
});
8

9
// Uses the global language ('en-GB')
10
const ukResults = await search({ query: 'restaurants', position: [4.9041, 52.3676] });
11

12
// Overrides the language for this call only
13
const frResults = await search({
14
    query: 'restaurants',
15
    position: [4.9041, 52.3676],
16
    language: 'fr-FR'
17
});

In the second call, language: 'fr-FR' wins over the global en-GB, but only for that request. The global configuration is left unchanged, so later calls still default to en-GB. This lets you set sensible application-wide defaults once and override individual options exactly where you need to.

For more advanced per-service customization — such as request validation, lifecycle hooks, and custom base URLs — see the Customizing services guide.

Setting configuration in Node.js

The same TomTomConfig singleton works in Node.js. Keep your API key out of source control by reading it from an environment variable:

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

3
TomTomConfig.instance.put({
4
    apiKey: process.env.TOMTOM_API_KEY,
5
    language: 'en-GB'
6
});

When to set configuration

Set your global configuration once, at application startup, before you create a map or call any service. Because the configuration is a shared singleton, there is no need to re-apply it per component or per request — every part of the SDK reads from the same instance.