POIs Module

The POIs Module controls Points of Interest displayed on the map, allowing you to show/hide POIs and filter them by category.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import {
    FilterablePOICategory,
    FilterShowMode,
    MapStylePOICategory,
    POICategoryGroup,
    POIsModule,
    TomTomMap,
    ValuesFilter,
} from '@tomtom-org/maps-sdk/map';
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 () => {
    let poisModule: POIsModule;
    let modeSelector: HTMLSelectElement;
    const filterInputs: HTMLInputElement[] = [];

    const categories: Partial<Record<FilterablePOICategory, string>> = {
        FOOD_DRINKS_GROUP: 'Food & Drinks',
        TRANSPORTATION_GROUP: 'Transportation',
        HOLIDAY_TOURISM_GROUP: 'Holiday & Tourism',
        HEALTH_GROUP: 'Health',
        PARKING_GROUP: 'Parking',
        SHOPPING_GROUP: 'Shopping',
        ACCOMMODATION_GROUP: 'Accommodation',
        ENTERTAINMENT_GROUP: 'Entertainment',
        GOVERNMENT_GROUP: 'Government Organizations',
        EDUCATION_GROUP: 'Education',
        GAS_STATIONS_GROUP: 'Gas Stations',
        EV_CHARGING_STATIONS_GROUP: 'EV Charging Stations',
    };

    let categoryFilter: ValuesFilter<FilterablePOICategory> = {
        show: 'all_except',
        values: [],
    };

    const toggleCategoryFilter = (category: MapStylePOICategory | POICategoryGroup, isChecked: boolean) => {
        isChecked
            ? categoryFilter.values.push(category)
            : (categoryFilter.values = categoryFilter.values.filter((cat) => cat != category));
        poisModule.filterCategories(categoryFilter);
    };

    const changeFilterMode = (mode: FilterShowMode) => {
        categoryFilter.show = mode;
        poisModule.filterCategories(categoryFilter);
    };

    const resetConfig = () => {
        categoryFilter = {
            show: 'all_except',
            values: [],
        };
        poisModule.filterCategories(categoryFilter);
        filterInputs.forEach((input) => (input.checked = categoryFilter.values.includes(input.value)));
        modeSelector.selectedIndex = 0;
    };

    const createFilterToggles = () => {
        const container = document.getElementById('sdk-example-filters-container');
        for (const [key, value] of Object.entries(categories)) {
            const item = document.createElement('div');
            item.className = 'sdk-example-item';
            const input = document.createElement('input');
            input.type = 'checkbox';
            input.value = key;
            input.checked = categoryFilter.values.includes(input.value);
            input.id = key;
            const label = document.createElement('label');
            label.htmlFor = key;
            label.innerText = value as string;
            item.appendChild(input);
            item.appendChild(label);
            filterInputs.push(input);
            container?.appendChild(item);
        }
    };

    const listenToUserEvents = () => {
        const items = document.querySelectorAll('.sdk-example-item input');
        items.forEach((item) =>
            item.addEventListener('change', (e) => {
                const target = e.target as HTMLInputElement;
                toggleCategoryFilter(target.value, target.checked);
            }),
        );

        modeSelector = document.getElementById('sdk-example-mode-selector') as HTMLSelectElement;
        modeSelector?.addEventListener('change', (e) =>
            changeFilterMode((e.target as HTMLSelectElement).value as FilterShowMode),
        );

        const resetBtn = document.getElementById('sdk-example-reset');
        resetBtn?.addEventListener('click', resetConfig);
    };

    const map = new TomTomMap({
        mapLibre: {
            container: 'sdk-map',
            center: [4.89437, 52.36859],
            zoom: 16.5,
        },
    });
    poisModule = await POIsModule.get(map);

    createFilterToggles();
    listenToUserEvents();
})();

Initialization

import { TomTomMap, POIsModule } from '@tomtom-org/maps-sdk/map';
// Initialize map
const map = new TomTomMap({ mapLibre: { container: 'map' } });
// Get POIs module
const poisModule = await POIsModule.get(map);

Visibility Control

Control POI layer visibility on the map:

// Initialize with hidden POIs
const poisModule = await POIsModule.get(map, {
visible: false
});
// Hide all POIs
poisModule.setVisible(false);
// Show all POIs
poisModule.setVisible(true);
// Check current visibility state
const visible = poisModule.isVisible();

Filtering

Filter POIs by individual categories or category groups:

// Filter on initialization
const poisModule = await POIsModule.get(map, {
visible: true,
filters: {
categories: {
show: 'only',
values: ['RESTAURANT', 'CAFE_PUB']
}
}
});
// Show categories
poisModule.filterCategories({
show: 'only',
values: ['RESTAURANT', 'CAFE_PUB', 'HOTEL_MOTEL']
});
// Hide categories
poisModule.filterCategories({
show: 'all_except',
values: ['PARKING_GARAGE', 'OPEN_PARKING_AREA']
});
// Show category groups
pois.filterCategories({
show: 'only',
values: ['FOOD_DRINKS_GROUP', 'SHOPPING_GROUP']
});
// Hide category groups
pois.filterCategories({
show: 'all_except',
values: ['PARKING_GROUP', 'GAS_STATIONS_GROUP']
});
// Reset filter and show all categories
pois.filterCategories(undefined);

Available Category Groups

The module supports predefined category groups for convenient filtering:

  • FOOD_DRINKS_GROUP - Restaurants, cafes, fast food, pubs, wineries
  • SHOPPING_GROUP - Stores, malls, markets, supermarkets
  • TRANSPORTATION_GROUP - Airports, train stations, bus stops, ferry terminals
  • HEALTH_GROUP - Hospitals, clinics, pharmacies, doctors, dentists
  • PARKING_GROUP - Parking garages and open parking areas
  • HOLIDAY_TOURISM_GROUP - Tourist attractions, museums, beaches, scenic views
  • EV_CHARGING_STATIONS_GROUP - Electric vehicle charging stations
  • GAS_STATIONS_GROUP - Gas and petrol stations
  • ACCOMMODATION_GROUP - Hotels, motels, camping grounds
  • ENTERTAINMENT_GROUP - Cinemas, theaters, nightlife, casinos
  • SPORTS_LEISURE_GROUP - Stadiums, sports centers, swimming pools, golf courses
  • EDUCATION_GROUP - Schools, universities, libraries, cultural centers
  • GOVERNMENT_GROUP - Government offices, courthouses, embassies, police, fire stations

Events

Handle user interactions with POIs:

// Click events
pois.events.on('click', (feature, lngLat) => {
console.log('POI name:', feature.properties.name);
console.log('Category:', feature.properties.category);
console.log('ID:', feature.properties.id);
console.log('Click coordinates:', lngLat);
});
// Hover events
pois.events.on('hover', (feature, lngLat) => {
console.log('Hovering over:', feature.properties.name);
});
// Context menu (right-click)
pois.events.on('contextmenu', (feature, lngLat) => {
console.log('Right-clicked POI:', feature.properties.name);
});
// Long hover
pois.events.on('long-hover', (feature, lngLat) => {
console.log('Long hover on:', feature.properties.name);
});
// Remove event listeners
pois.events.off('click', handler);

POI Feature Properties

POI features include the following properties in events:

  • id - Unique POI identifier
  • name - POI name in native language
  • category - POI category (e.g., ‘RESTAURANT’, ‘HOTEL_MOTEL’)
  • iconID - Icon sprite ID used for rendering
  • group - Category group the POI belongs to
  • priority - Importance level (lower number = more important)

API Reference

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

Services Integration

  • Search Services - Find places and display them with the Places Module alongside filtered POIs