POIs module

The POIs module controls the points of interest the map style draws. To draw search results or your own points, use the Places module.

The module owns whether the style’s POI layers are shown, which categories show and how they look. The look covers icon size, the zoom POIs appear at, label colours, micro markers (Appearance) and any custom icon a category is drawn with. Who owns what compares every module.

Initialization

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

3
const map = new TomTomMap({ mapLibre: { container: 'map' } });
4
const poisModule = await POIsModule.get(map);

The POIs belong to the style, so POIsModule.get returns the one instance a map has. A setting you apply through one handle shows through every other. A configuration passed to a later get replaces the one it holds, as applyConfig does.

Visibility control

1
const poisModule = await POIsModule.get(map, { visible: false });
2

3
poisModule.setVisible(true);
4
poisModule.isVisible(); // true

isVisible() returns the visible setting. Until something sets it, it reports whether the style draws any POI layer.

Every setting as data

poisKnobCatalogue lists the module’s settings that a single control can hold, with their kind, a description and their default, if any. You can read it with no map loaded:

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

3
const visible = poisKnobCatalogue.find(({ id }) => id === 'visible');
4
// { id: 'visible', kind: 'toggle', description: 'The POIs the map style draws.', default: true }
5
const values = poisKnobCatalogue.find(({ id }) => id === 'filters.categories.values');
6
// { id: 'filters.categories.values', kind: 'enums', description: '…', options: ['FOOD_DRINKS_GROUP', …, 'RESTAURANT', …] }

• filters.categories.show and filters.categories.values are the category filter, which applies once both are set. The options of filters.categories.values are the category groups, then every individual category.
• The rest set how POIs look (Appearance).
• icon.categoryIcons is not in the catalogue, because it takes images.
• setKnob, getKnob and resetKnob set, read and reset a setting by its id (Setting a knob by its id).
• poisKnobIds lists the ids, POIsKnobId is their union, and POIsKnobValueOf<ID> is the plain value one takes. Entries in every module’s catalogue share this shape, KnobEntry.

Filtering

filters.categories shows only the categories and category groups it lists, or all-except them:

1
const poisModule = await POIsModule.get(map, {
2
    filters: { categories: { show: 'only', values: ['RESTAURANT', 'CAFE_PUB'] } },
3
});
4

5
poisModule.updateConfig({
6
    filters: { categories: { show: 'all-except', values: ['PARKING_GROUP', 'OPEN_CAR_PARKING_AREA'] } },
7
});
8

9
// Every category again
10
poisModule.updateConfig({ filters: undefined });

• Categories and groups can mix in one list. A group stands for each of its categories.
• show takes one of filterShowModes ('only', 'all-except'), which @tomtom-org/maps-sdk/map exports for building a mode picker or a schema.
• poiCategoryGroups maps each group name to its categories.

Available category groups

• 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

Appearance

The size of the POIs, the zoom they appear at, their label colours and the micro markers restyle the style’s own POI layers. Each keeps the style’s value until you set it:

1
import { POIsModule, poisKnobCatalogue, setKnob } from '@tomtom-org/maps-sdk/map';
2

3
const poisModule = await POIsModule.get(map, {
4
    sizeFactor: 1.2,
5
    minZoom: 12,
6
    label: { color: '#334155', haloColor: '#ffffff' },
7
    microMarkers: { visible: false },
8
});
9
setKnob(poisModule, poisKnobCatalogue, 'zoomShift', 1); // later and sparser

• sizeFactor multiplies with the labels.sizeFactor and symbols.sizeFactor of the Styling Foundations module, which reach the POIs too.
• zoomShift combines with the category filter in either order, because it rewrites the same layer filters filters.categories narrows.
• microMarkers.visible can only hide. Micro markers never show while the POIs are hidden, and setVisible(true) doesn’t override a false.
• Places drawn with the base-map marker type borrow this look, and getStyleColor reads the label colours as pois.label.color and pois.label.haloColor.

Custom icons per category

icon.categoryIcons draws the POIs of a category with your own image. Every other category keeps the style’s icon. It takes the same entries as the Places module, so one list restyles the map’s POIs and the places you show:

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

3
const categoryIcons = [
4
    { id: 'RESTAURANT', image: restaurantSvg },
5
    { id: 'HOTEL_OR_MOTEL', image: '/icons/hotel-pin.png', offsetY: -17 },
6
];
7

8
const poisModule = await POIsModule.get(map, { icon: { categoryIcons } });
9
const searchResults = await PlacesModule.create(map, { markerType: 'base-map', icon: { categoryIcons } });
10

11
// The style's own icons again
12
poisModule.updateConfig({ icon: undefined });

• An entry applies to its whole map category. The map knows fewer categories than search does, so CAFE and CAFE_PUB are both cafés on the map, and the first entry listed wins.
• The image is drawn centred on the POI at the style’s icon size, sizeFactor included. An image as large as a POI icon keeps the map’s density. offsetX and offsetY move it in pixels, to stand a pin’s tip on its POI.
• Entries without an image change nothing, and the micro markers of minor POIs keep the style’s dots.
• The icons survive a style change, but a switch that resets the map’s state drops them.

Events

click, contextmenu, hover and long-hover hand over the POI under the pointer (event types):

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

3
const stopListening = poisModule.events.on('click', async (feature, lngLat) => {
4
    console.log(feature.properties.name, feature.properties.category, lngLat);
5
    // The POI id is a place id: fetch its opening hours, phone and more
6
    const place = await getPlaceDetails({ entityId: feature.properties.id });
7
});
8
poisModule.events.on('hover', (feature) => console.log(feature.properties.name));
9

10
stopListening(); // removes this handler alone
11
poisModule.events.off('hover'); // removes every hover handler

POI feature properties

A POI feature (POIsModuleFeature) carries the style’s own values:

• id - The POI’s id, which getPlaceDetails takes as entityId.
• name - The name in the country’s own language.
• category - The style’s category, in lower case ('restaurant', 'hotel_or_motel'), not the upper-case category code the filters and categoryIcons take.
• group - The style’s category group ('eat_and_drink', …).
• priority - Importance. A lower number is more important.

Querying visible features

getRenderedFeatures() returns the POI features rendered in the viewport:

1
const { pois } = poisModule.getRenderedFeatures();
2
pois.forEach((poi) => console.log(poi.properties.name, poi.properties.category));

API reference

POIsModule lists every method, and POIsModuleConfig every setting.

Related guides and examples

Services integration

• Place details - Full details (opening hours, phone, URL) of a clicked POI
• POI categories - The category codes search and these filters share

Related examples

• POI filters - Interactive POI category filtering
• Interactive map POIs - Clicks and hovers on the map’s own POIs
• POI category icons playground - A circle, square, diamond or pin per category, on the map’s POIs and on searched places alike

Related map modules

• Map styling - Label and icon sizes across the whole map, which compose with the POIs’ own sizeFactor, and the map presets that set POI knobs too
• Places module - Search results and your own points, drawn as markers
• User interaction events - Event types, cursors and event states across modules