Geometry Module

VERSION 0.41.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';

// (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-place-selector') 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();
})();

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
});

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);

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