Places Module

VERSION 0.41.1 PUBLIC PREVIEW

The Places module allows you to display and interact with places on your TomTom map. You can add search results, custom locations, and handle user interactions.

import { bboxFromGeoJSON, TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { PlacesModule, TomTomMap } from '@tomtom-org/maps-sdk/map';
import { geocode } from '@tomtom-org/maps-sdk/services';
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-US' });

(async () => {
    const [firstGroup, secondGroup, thirdGroup] = await Promise.all([
        geocode({ query: '1051', countries: ['NL'] }), // searching for locations by postcode
        geocode({ query: '1052', countries: ['NL'] }),
        geocode({ query: '1053', countries: ['NL'] }),
    ]);

    const map = new TomTomMap({
        mapLibre: {
            container: 'sdk-map',
            bounds: bboxFromGeoJSON([firstGroup, secondGroup]),
            fitBoundsOptions: { padding: 50 },
        },
    });

    const firstPlacesModule = await PlacesModule.get(map, {
        icon: { default: { style: { fillColor: '#FFBF00', outlineColor: '#113300', outlineOpacity: 0.25 } } },
    });
    await firstPlacesModule.show(firstGroup);

    const secondPlacesModule = await PlacesModule.get(map, {
        icon: { default: { style: { fillColor: 'lightblue', outlineColor: 'grey', outlineOpacity: 0.5 } } },
    });
    await secondPlacesModule.show(secondGroup);

    const thirdPlacesModule = await PlacesModule.get(map, {
        icon: { default: { style: { fillColor: '#FFBBCC', outlineColor: 'red', outlineOpacity: 0.25 } } },
    });
    await thirdPlacesModule.show(thirdGroup);
})();

Open Sandbox

Initialization

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

3
// Initialize map
4
const map = new TomTomMap({ mapLibre: { container: 'map' } });
5

6
// Initialize Places module with default configuration
7
const placesModule = await PlacesModule.get(map);

Displaying Places

Display one or multiple places on the map:

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

3
// Show single place
4
await placesModule.show({
5
  id: 'custom-place-1',
6
  type: 'Feature',
7
  geometry: { type: 'Point', coordinates: [4.9041, 52.3676] },
8
  properties: {
9
    type: 'POI',
10
    address: { freeformAddress: 'Custom Place 1, Amsterdam' },
11
    poi: { name: 'Custom Place' }
12
  }
13
});
14

15
// Show multiple places
16
await placesModule.show([place1, place2, place3]);
17

18
const searchResults = await search({
19
    query: 'restaurants',
20
    position: [4.9041, 52.3676], // Amsterdam
21
    limit: 10
22
});
23

24
// Show search results
25
await placesModule.show(searchResults);
26

27
// Remove all places from the map:
28
await placesModule.clear();

Custom Styling

Text Styling

Customize labels for places using text configuration:

1
// Make POI names red and other places blue
2
const customTextConfig: PlaceTextConfig = {
3
    textColor: ['match', ['get', 'type'], 'POI', '#D32F2F', '#1976D2']
4
};
5

6
// Initialize with custom text styling
7
const placesModule = await PlacesModule.get(map, {
8
    text: customTextConfig,
9
});
10

11
// Or apply after initialization
12
placesModule.applyTextConfig(customTextConfig);

Icon Styling

Customize place icons and markers:

1
// Use circle markers instead of pins
2
const customIconConfig: PlaceIconConfig = {
3
  iconStyle: 'circle'
4
}
5

6
// Initialize with custom icon styling
7
const placesModule = await PlacesModule.get(map, {
8
  icon: customIconConfig
9
});
10

11
// Or apply after initialization
12
placesModule.applyIconConfig(customIconConfig);

Extra Properties

Add custom properties to places for advanced styling or filtering:

1
placesModule.applyExtraFeatureProps({
2
    category: (place) => place.properties.poi?.categories?.[0],
3
    rating: (place) => place.properties.poi?.rating || 0,
4
    isOpen: true
5
});

Events

User events

Handle user interactions with places:

1
// Click events
2
placesModule.events.on('click', (feature, lngLat) => {
3
    console.log('Click coordinates:', lngLat);
4
    console.log('Place title:', feature.properties.title);
5
    console.log('Place coordinates:', feature.geometry.coordinates);
6
});
7

8
// Hover events
9
placesModule.events.on('hover', (feature, lngLat) => {
10
    console.log('Hovering over:', feature.properties.poi?.name);
11
});
12

13
// Remove event listeners
14
placesModule.events.off('click', handler);

Programmatic Event States

Manually control visual states of places:

1
// Highlight first place as if clicked
2
placesModule.putEventState({
3
    index: 0,
4
    state: 'click',
5
    mode: 'put'
6
});
7

8
// Remove event state from specific place
9
placesModule.cleanEventState({ index: 0 });
10

11
// Remove all hover states
12
placesModule.cleanEventStates({ states: ['hover'] });
13

14
// Remove all event states
15
placesModule.cleanEventStates();

Multiple Module Instances

You can create multiple independent instances of the Places module, each with its own configuration and data. This is useful for displaying different sets of places with distinct styling or behavior.

1
// Create separate instances for different purposes
2
const restaurantPlaces = await PlacesModule.get(map, {
3
    icon: { iconStyle: 'pin', iconColor: '#FF5733' }
4
});
5

6
const hotelPlaces = await PlacesModule.get(map, {
7
    icon: { iconStyle: 'circle', iconColor: '#3498DB' }
8
});
9

10
// Each instance manages its own places independently
11
await restaurantPlaces.show(restaurantResults);
12
await hotelPlaces.show(hotelResults);

API Reference

For complete documentation of all Places Module properties, methods, and types, see the BaseMapModule API Reference .

Services Integration

Search Services - Find places and POIs to display using the Places Module with autocomplete, fuzzy search, and geometry search
Geocoding - Convert addresses to coordinates for precise place positioning on the map
Reverse Geocoding - Get address information for places and display them with rich location context

Places Customize - Advanced place styling and customization techniques
Places in Geometry - Display places within specific geographic boundaries
Fuzzy Search Playground - Search for places and display results interactively
Geometry Search with POI Categories - Category-filtered place discovery and visualization
Pin Interaction - Interactive place markers with click events and popups

POIs - Advanced point-of-interest filtering and categorization for places
User Interaction Events - Handle user interactions with places on the map