Places Module

VERSION 0.48.3 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 { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { PlacesModule, TomTomMap } from '@tomtom-org/maps-sdk/map';
import { geocodeOne, search } 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 });

(async () => {
    const location = await geocodeOne('London Covent Garden');

    const map = new TomTomMap({
        mapLibre: {
            container: 'sdk-map',
            bounds: location.bbox,
        },
    });

    const parkingSpots = await search({
        poiCategories: ['PARKING_GARAGE', 'OPEN_CAR_PARKING_AREA', 'ELECTRIC_VEHICLE_STATION'],
        position: location,
        limit: 50,
    });

    const placesModule = await PlacesModule.get(map);
    placesModule.show(parkingSpots);
})();

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

Theme

Themes control the overall look of place markers. Choose one at initialization or swap at runtime:

pin (default): traditional teardrop pin markers
circle-icon: circular markers with a centered category icon
base-map: mimics the base map style’s POI layer, combining main, selected, and micro layers so places blend in with the style’s built-in POIs. To render exclusively through the lightweight POI - Micro layer — ideal for dense results where a full POI treatment would be too heavy — hide the main layer via layers.main.layout.visibility = 'none'.

1
// Initialize with a specific theme
2
const placesModule = await PlacesModule.get(map, { theme: 'base-map' });
3

4
// Or swap at runtime
5
placesModule.applyTheme('circle-icon');
6

7
// Micro-only rendering: combine `base-map` with a hidden `main` layer
8
const placesModule = await PlacesModule.get(map, {
9
    theme: 'base-map',
10
    layers: { main: { layout: { visibility: 'none' } } },
11
});

Text Styling

Customize labels for places using text configuration:

1
// Make POI names red and other places blue
2
const customTextConfig: PlaceTextConfig = {
3
    color: ['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. Custom icons work under every theme: when a category is mapped, features in that category use the provided sprite; otherwise the theme’s default icon (the base-map style’s category/group expression or the default pin) still renders.

1
// Per-category custom images — layered on top of any theme
2
const customIconConfig: PlaceIconConfig = {
3
  categoryIcons: [
4
    { id: 'RESTAURANT', image: '/icons/food.png', pixelRatio: 2 },
5
    { id: 'HOTEL_MOTEL', image: '/icons/hotel.png', pixelRatio: 2 }
6
  ]
7
};
8

9
// Initialize with custom icon styling
10
const placesModule = await PlacesModule.get(map, {
11
  theme: 'pin',
12
  icon: customIconConfig
13
});
14

15
// Or apply after initialization
16
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
    theme: 'pin',
4
    icon: {
5
        categoryIcons: [{ id: 'RESTAURANT', image: '/icons/restaurant.png', pixelRatio: 2 }]
6
    }
7
});
8

9
const hotelPlaces = await PlacesModule.get(map, {
10
    theme: 'circle-icon',
11
    icon: {
12
        categoryIcons: [{ id: 'HOTEL_MOTEL', image: '/icons/hotel.png', pixelRatio: 2 }]
13
    }
14
});
15

16
// Each instance manages its own places independently
17
await restaurantPlaces.show(restaurantResults);
18
await hotelPlaces.show(hotelResults);

Reading Shown Data

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

1
const shown = placesModule.getShown();
2
console.log(`Showing ${shown.places.features.length} places`);

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