Global configuration

The global configuration holds the settings your whole application shares: API key, language, geopolitical view, base URL, display units and retry behaviour. Every map and service call reads it, so you don’t pass the API key to each one.

Set it once at startup, before you create a map or call a service, in the browser or in Node.js. These values are defaults, and a map or a single call can override any of them.

The TomTomConfig singleton

TomTomConfig.instance, exported from the Core bundle, holds this configuration:

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

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

In Node.js, read the key from the environment instead of your source code: TomTomConfig.instance.put({ apiKey: process.env.TOMTOM_API_KEY }). Where your API key runs explains when this keeps the key private.

The three methods

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

3
TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' }); // merge values in
4
const config = TomTomConfig.instance.get();            // read the current values
5
TomTomConfig.instance.reset();                         // restore the defaults

• put(config) - Merges the given keys over the current ones. Keys you leave out keep their value.
• get() - Returns the current configuration object.
• reset() - Restores the defaults. The default apiKey is an empty string, so set a key again afterwards.

put performs a shallow merge

put merges top-level keys only. It replaces a nested object such as displayUnits whole. The one exception is retry.

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

3
// Replaces displayUnits: the distance setting above is gone
4
TomTomConfig.instance.put({ displayUnits: { time: { hours: 'hrs' } } });

To change one nested field, pass the whole nested object again.

Configuration options

apiKey

Your TomTom API key, from my.tomtom.com. To decide where to keep it, read Where your API key runs and TomTom’s API key management best practices.

commonBaseURL

The base URL of every TomTom request, which covers service calls and the style, tile, sprite and glyph URLs the map fetches. Change it only to route these requests through your own proxy.

Proxy mode depends on apiKey being unset. If you leave a key set, the SDK still sends it. Proxying your API calls covers the proxy side.

The URL must be absolute and use https:. The SDK accepts http: only for a loopback address (localhost, 127.0.0.0/8, [::1]) in local development. Any other http: URL would send your key unencrypted, so service calls reject and the map constructor throws with the code INSECURE_BASE_URL. Note that validateRequest: false does not skip this check.

language

An IETF language code (case-insensitive) for search results, routing instructions, map labels and traffic incident descriptions. If you don’t set it, the APIs answer in NGT (Neutral Ground Truth), which names each place in its local language. For the supported languages, see Search and Routing.

The SDK exports the codes it accepts as the languages array, typed as Language, so you can build a language picker from it:

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

3
const picker = document.querySelector<HTMLSelectElement>('#language');
4
picker?.replaceChildren(...languages.map((code) => new Option(code, code)));
5
picker?.addEventListener('change', () => TomTomConfig.instance.put({ language: picker.value as Language }));

geopoliticalView

Whose perspective disputed territories are shown from, on the map and in search and geocoding results. If you don’t set it, each TomTom API applies the default view for the country the request comes from. Geopolitical views lists the views and which APIs support them.

sendUserAgentHeader

Every service call, and every map request except images, carries a tomtom-user-agent header with the SDK name and version (MapsSDKJS/<version>). TomTom uses it to see which SDK versions are in use. It carries nothing about your app or its users.

1
TomTomConfig.instance.put({ sendUserAgentHeader: false });

• Turn it off when the header must not leave the page, or when your proxy should not have to allow it.
• A TomTomMap keeps the value it was created with. Set sendUserAgentHeader: false before you create the map, or pass it in its params.

displayUnits

The unit system ('metric', 'imperial_us' or 'imperial_uk') and unit labels that formatDistance and formatDuration use for every distance and duration the SDK displays.

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

A RoutingModule with no displayUnits of its own labels its routes in these units, as Routes describes.

Pick a unit system below. The route’s summary bubble and speed limit signs change with the summary printed by formatDistance and formatDuration, and the route is not calculated again.

retry

When a service request gets a rate-limited (429) response, the SDK retries it with exponential backoff. If the response has a Retry-After header, the SDK waits as long as it asks.

1
TomTomConfig.instance.put({
2
    retry: {
3
        initialWaitMs: 0.447, // first wait, when there is no Retry-After header
4
        backoffFactor: 1.618, // multiplier applied to the wait after each retry
5
        timeoutMs: 40000      // give up once the next wait would pass this, counted from the first request
6
    }
7
});

• A field you leave out takes its default, not the value from an earlier put. For example, put({ retry: { timeoutMs: 10000 } }) keeps the default wait and factor.
• To turn retrying off, set retry: undefined. The first 429 then rejects the call.
• When the next wait would exceed timeoutMs, the call rejects with the 429 as an SDKServiceError.
• timeoutMs limits the retrying, not a single request. To set a deadline for one call, use a signal.

How global and per-request configuration combine

Every service call merges its own parameters over the global configuration. The per-call value wins for that call only:

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

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

6
// Uses the global language ('en-GB')
7
const ukResults = await discoverPlaces({ query: 'restaurants', geoBias: { position: [4.9041, 52.3676] } });
8

9
// French for this call only; the global configuration stays 'en-GB'
10
const frResults = await discoverPlaces({
11
    query: 'restaurants',
12
    geoBias: { position: [4.9041, 52.3676] },
13
    language: 'fr-FR'
14
});

• A TomTomMap takes the same keys in its constructor parameters, overriding the global values for that map.
• A call’s retry merges into the global one rather than replacing it, as Per-call overrides describes.
• Service calls don’t take displayUnits. To override it, pass it where the SDK displays units, which is the formatters’ second argument or the RoutingModule config.
• Request options and errors covers the options that exist only per call, such as validation and cancellation.