Geopolitical views

Borders, names and addresses are disputed in many places, and what is correct depends on who is looking. A geopolitical view sets whose perspective the SDK shows in the borders and names the map draws, and in the country a search or reverse geocoding result reports. One setting controls both, so the map and your results never contradict each other.

Pick a territory and a view below. The borders redraw, and the address of the pinned place updates.

Supported views

geopoliticalViews, exported from the Core bundle, lists every view as the GeopoliticalView type:

Examples of what the views change:

• IN, PK, CN - The borders of Kashmir, Aksai Chin and Arunachal Pradesh, and the country of their addresses.
• MA, DZ - Western Sahara, as part of Morocco or as a territory of its own.
• KR - The East Sea and Dokdo.
• US - The Gulf of America.
• AE - The Arabian Gulf.
• VN, PH, MY - The Paracel and Spratly Islands.

Not every TomTom API supports every view:

If an API doesn't support a view, the SDK leaves the view out of its requests to it, so the call still succeeds in that API's default view.

servesGeopoliticalView(view, api) tells whether the SDK sends view to that API, so you can label a result with the view its request carried. The map and the services decide what to send from the same check, so your label and the request always agree. The api is one of mapTiles, search, placeDetails, reverseGeocoding and geocoding:

import { servesGeopoliticalView } from '@tomtom-org/maps-sdk/core';
import { reverseGeocode } from '@tomtom-org/maps-sdk/services';

const view = 'US';
const address = await reverseGeocode({ position: [-90.07, 29.95], geopoliticalView: view });

// Reverse geocoding doesn't support US, so the address is in your default view
const label = servesGeopoliticalView(view, 'reverseGeocoding') ? view : 'Default view';

Note that the check tells you the view the SDK sent, not the one the API applied, which can differ for requests from India.

Setting the view

Set the view once in the global configuration, and it applies to the map and to every search, place details, geocoding and reverse geocoding call:

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

TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY', geopoliticalView: 'IN' });

A map's constructor or a single call can override it:

import { TomTomMap } from '@tomtom-org/maps-sdk/map';
import { reverseGeocode } from '@tomtom-org/maps-sdk/services';

const map = new TomTomMap({ mapLibre: { container: 'map' }, geopoliticalView: 'PK' });

const address = await reverseGeocode({ position: [74.31, 35.92], geopoliticalView: 'Unified' });

When no view is set

If you don't set a view, each TomTom API applies the default view for the country the request comes from, as local law there requires. Requests from India always get the IN view, whatever view you set.

Switching the view on a map

setGeopoliticalView changes the view of a map that is already showing:

map.setGeopoliticalView('IN');

// Back to the default view for the viewer's country
map.setGeopoliticalView(undefined);

• The visible tiles reload in place. The camera, the style and every module stay as they are.
• The view persists across style changes, like the map language.
• It applies to the TomTom Orbis vector tiles.
• It changes the map only. To use the same view in services, also put it in the global configuration:

TomTomConfig.instance.put({ geopoliticalView: 'IN' });
map.setGeopoliticalView('IN');

Related guides and examples

• Global configuration
• TomTomMap
• Reverse geocoding
• Geopolitical views playground