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:

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

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

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

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

TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' }); // merge values in
const config = TomTomConfig.instance.get();            // read the current values
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. It holds apiKey, commonBaseURL, retry (unless you set it to undefined) and the keys you set. A key you never set reads undefined and behaves as its default in the table below.
• 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 or retry whole. A retry you pass also takes its missing fields from the defaults, not from an earlier put.

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

// Replaces displayUnits: the distance setting above is gone
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 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.

Language lists every language the map labels carry. A service that lacks one answers in local names. Search, geocoding and reverse geocoding do so for hi-IN and ja-JP. Text a service writes itself, such as route instructions, POI category names and traffic incident descriptions, comes in the nearest language it has, or in English. The SDK sends each API a code it takes, such as zh-CN for zh-Hans, and leaves the language off where the API has none close to it.

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

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

const picker = document.querySelector<HTMLSelectElement>('#language');
picker?.replaceChildren(...languages.map((code) => new Option(code, code)));
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.

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.

TomTomConfig.instance.put({
    displayUnits: {
        distance: { type: 'imperial_us', miles: 'miles' },
        time: { hours: 'hrs', minutes: 'mins' }
    }
});

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.

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

• Without a Retry-After header, each wait is drawn at random between half the backoff and the whole of it. That way, apps rate-limited at the same moment don't all retry together.
• 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.
• retry covers service calls only. The map loads its tiles, sprites and glyphs through MapLibre, which doesn't retry them, and reports a failed one to its error handlers.

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:

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

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

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

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

• 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.