Geometry Module

VERSION 0.46.1 PUBLIC PREVIEW

The Geometry Module in the TomTom Maps SDK enables displaying and visualizing geographic shapes and polygons on maps. This module provides comprehensive functionality for rendering complex geometries, administrative boundaries, and custom geographic data with customizable styling.

import type { BBox, Places } from '@tomtom-org/maps-sdk/core';
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import {
    calculateFittingBBox,
    GeometriesModule,
    type GeometryBeforeLayerConfig,
    type StandardStyleID,
    standardStyleIDs,
    TomTomMap,
} from '@tomtom-org/maps-sdk/map';
import { geocode, geometryData } from '@tomtom-org/maps-sdk/services';
import type { LngLatBoundsLike } from 'maplibre-gl';
import type { Config } from './placeConfiguration';
import { namedConfigs } from './placeConfiguration';
import './style.css';
import { API_KEY } from './config';
import { initTogglePanel } from './togglePanel';

// (Set your own API key when working in your own environment)
TomTomConfig.instance.put({ apiKey: API_KEY, language: 'en-GB' });

(async () => {
    const map = new TomTomMap({
        mapLibre: {
            container: 'sdk-map',
        },
    });
    const geometryModule = await GeometriesModule.get(map);
    let placeSubdivisions: Places;

    const placeBBox = () =>
        calculateFittingBBox({
            map,
            toBeContainedBBox: placeSubdivisions.bbox as BBox,
            surroundingElements: ['#sdk-example-panel'],
        }) as LngLatBoundsLike;

    const updateMap = async (config: Config) => {
        placeSubdivisions = await geocode({ limit: 100, query: '', ...config.searchConfig });
        map.mapLibreMap.fitBounds(placeBBox());
        const geometries = await geometryData({ geometries: placeSubdivisions, zoom: 14 });
        geometryModule.applyConfig(config.geometryConfig);
        geometryModule.show(geometries);
    };

    const listenToUIEvents = async () => {
        const placeSelector = document.getElementById('sdk-example-placeSelector') as HTMLSelectElement;
        placeSelector.addEventListener('change', (event) =>
            updateMap(namedConfigs[(event.target as HTMLInputElement).value]),
        );

        const options = document.querySelectorAll<HTMLInputElement>('input[type=radio][name=layerOption]');
        options.forEach((option) => {
            option.addEventListener('change', () =>
                geometryModule.moveBeforeLayer(option.value as GeometryBeforeLayerConfig),
            );
        });

        const stylesSelector = document.querySelector('#sdk-example-mapStyles') as HTMLSelectElement;
        standardStyleIDs.forEach((id) => stylesSelector.add(new Option(id)));
        stylesSelector.addEventListener('change', (event) =>
            map.setStyle((event.target as HTMLOptionElement).value as StandardStyleID),
        );

        document
            .querySelector('#sdk-example-reCenter')
            ?.addEventListener('click', () => placeSubdivisions && map.mapLibreMap.fitBounds(placeBBox()));
    };

    await updateMap(namedConfigs.france);
    await listenToUIEvents();

    initTogglePanel();
})();

Open Sandbox

Purpose and Functionality

The Geometry Module serves as the primary interface for:

Displaying polygon geometries from TomTom services and custom data
Visualizing administrative boundaries such as countries, states, and cities
Rendering custom geographic shapes with configurable styling options
Managing geometry layers with visibility controls and interaction handling
Integrating geometry data from search results and external sources

Core Concepts

Geometry Data Types

The module supports various types of geographic geometries:

Supported Geometry Types:

Polygons: Closed shapes representing areas like administrative boundaries
MultiPolygons: Complex shapes with multiple disconnected areas
Administrative boundaries: Country, state, city, and district boundaries
Custom shapes: User-defined geographic areas and regions

Data Sources

Geometries can come from multiple sources:

TomTom Geometry Data Service: Official administrative boundaries and places
Search results: Geographic data from place searches
Custom GeoJSON: User-provided geometric data
External APIs: Third-party geographic data sources

Basic Geometry Display

Initializing Geometry Module

1
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
2
import { TomTomMap, GeometriesModule } from '@tomtom-org/maps-sdk/map';
3

4
// Configure SDK and create map
5
TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });
6
const map = new TomTomMap({ mapLibre: { container: 'map' } });
7

8
// Initialize geometry module with default styling
9
const geometryModule = await GeometriesModule.get(map);

Displaying Administrative Boundaries

1
import { geocode, geometryData } from '@tomtom-org/maps-sdk/services';
2

3
// Get geometry for a specific place
4
const place = (await geocode({ query: 'Amsterdam, Netherlands' })).features[0];
5
const geometryResponse = await geometryData({ geometries: [place] });
6

7
// Display the geometry on the map
8
geometryModule.show(geometryResponse);

Custom Styling Configuration

1
// Initialize with custom styling
2
const geometryModule = await GeometriesModule.get(map, {
3
    colorConfig: {
4
        fillColor: '#007cbf',      // Fill color for polygons
5
        fillOpacity: 0.3           // Fill transparency
6
    },
7
    lineConfig: {
8
        lineColor: '#005a8b',      // Border color
9
        lineWidth: 2,              // Border width
10
        lineOpacity: 0.8           // Border transparency
11
    },
12
    beforeLayerConfig: 'road-labels' // Layer positioning
13
});

Advanced Geometry Features

Multiple Geometry Layers

1
// Create multiple geometry modules for different data sets
2
const countryGeometryModule = await GeometriesModule.get(map, {
3
    colorConfig: { fillColor: '#ff6b6b', fillOpacity: 0.2 },
4
    lineConfig: { lineColor: '#ff0000', lineWidth: 3 }
5
});
6

7
const cityGeometryModule = await GeometriesModule.get(map, {
8
    colorConfig: { fillColor: '#4ecdc4', fillOpacity: 0.4 },
9
    lineConfig: { lineColor: '#00a896', lineWidth: 2 }
10
});
11

12
// Display different geometry types
13
countryGeometryModule.show(countryBoundaries);
14
cityGeometryModule.show(cityBoundaries);

Dynamic Geometry Management

1
// Add and remove geometries dynamically
2
const geometryModule = await GeometriesModule.get(map);
3

4
// Show new geometry data
5
function displayGeometry(newGeometryData) {
6
    geometryModule.clear(); // Clear existing geometries
7
    geometryModule.show(newGeometryData);
8
}
9

10
// Toggle geometry visibility
11
let geometryVisible = true;
12
function toggleGeometry() {
13
    if (geometryVisible) {
14
        geometryModule.clear();
15
    } else {
16
        geometryModule.show(currentGeometryData);
17
    }
18
    geometryVisible = !geometryVisible;
19
}

Layer Positioning and Styling

1
// Advanced styling with layer control
2
const geometryModule = await GeometriesModule.get(map, {
3
    beforeLayerConfig: 'road-labels',  // Position below road labels
4
    colorConfig: {
5
        fillColor: '#87CEEB',
6
        fillOpacity: 0.5
7
    },
8
    lineConfig: {
9
        lineColor: '#4682B4',
10
        lineWidth: 1.5,
11
        lineOpacity: 1
12
    }
13
});

Themed Geometry Display

The SDK supports three visual themes for polygon display:

Theme	Effect
`'filled'`	Semi-transparent fill (default)
`'outline'`	Transparent fill with a thick border
`'inverted'`	Semi-transparent area outside the polygon

Setting theme at config level

The simplest way to apply a theme is via the theme option in GeometriesModuleConfig:

1
import { GeometriesModule } from '@tomtom-org/maps-sdk/map';
2

3
// Highlight "rest of the world" outside a country
4
const module = await GeometriesModule.get(map, {
5
    theme: 'inverted',
6
    colorConfig: { fillColor: 'black', fillOpacity: 0.5 },
7
});
8
module.show(countryGeometry);

Individual features can override the config-level theme by setting theme in their own properties.

Using `themedGeometryConfig` for mixed themes

When features in the same layer need different themes, use themedGeometryConfig(palette?). It returns a config with MapLibre expressions that read each feature’s theme property and apply the appropriate style:

1
import { GeometriesModule, themedGeometryConfig } from '@tomtom-org/maps-sdk/map';
2

3
const module = await GeometriesModule.get(map, themedGeometryConfig('blues'));
4

5
// Features carry their own theme — styling adapts per feature
6
module.show({
7
    type: 'FeatureCollection',
8
    features: [
9
        { ...featureA, properties: { theme: 'filled', title: 'Zone A' } },
10
        { ...featureB, properties: { theme: 'outline', title: 'Zone B' } },
11
    ],
12
});

A center label is shown for each polygon whenever the feature carries a title property.

Color palettes

Both themedGeometryConfig and reachableRangeGeometryConfig accept a named palette as their first argument (defaulting to 'fadedRainbow'). The palette controls the fill colors assigned to successive polygon rings.

Available palettes: warm, browns, cold, fadedBlues, blues, greens, fadedGreenToBlue, blueToRed, greenToYellow, pastel, retro, contrastRetro, fadedRainbow, pastelRainbow.

1
import { themedGeometryConfig } from '@tomtom-org/maps-sdk/map';
2

3
// Use the 'retro' palette with filled theme (default)
4
const config = themedGeometryConfig('retro');
5

6
// Palette names are typed as ColorPaletteOptions

For reachable ranges specifically, use reachableRangeGeometryConfig which builds on themedGeometryConfig and additionally wires up label generation and the inverted-theme donut transform automatically. See Reachable Ranges .

Multiple Module Instances

You can create multiple independent instances of the Geometry module, each with its own configuration and styling. This is useful for displaying different geometry layers with distinct visual styles.

1
// Create separate instances for different geometry types
2
const countryBorders = await GeometriesModule.get(map, {
3
    colorConfig: { fillColor: '#E74C3C', fillOpacity: 0.2 },
4
    lineConfig: { lineColor: '#C0392B', lineWidth: 3 }
5
});
6

7
const cityBounds = await GeometriesModule.get(map, {
8
    colorConfig: { fillColor: '#3498DB', fillOpacity: 0.3 },
9
    lineConfig: { lineColor: '#2980B9', lineWidth: 2 }
10
});
11

12
// Each instance manages its own geometries independently
13
countryBorders.show(countryData);
14
cityBounds.show(cityData);

Reading Shown Data

Use getShown() to retrieve the geometries currently displayed on the map. This returns the exact data previously passed to show():

1
const shown = geometriesModule.getShown();
2
console.log(`Geometries: ${shown.geometry.features.length}`);

Services Integration

Geometry Data Service - Fetch detailed boundary and shape data for administrative areas and places
Search Services - Find places and administrative areas that have associated geometry data

Basic Geometry - Simple geometry display and styling examples
Multiple Geometries - Working with multiple geometry layers and data sets
Multiple Geometry Modules - Advanced geometry module management and organization
Places in Geometry - Combining geometry boundaries with place markers
Geometry Search Playground - Interactive geometry-based search and discovery

Places Module - Display places and POIs within or related to geometric boundaries
Routing Module - Show routes that intersect or travel through geometric areas
User Interaction Events - Handle user interactions with geometric shapes and boundaries