POI Categories

VERSION 0.46.1 PUBLIC PREVIEW

The POI categories service returns the complete list of Point of Interest category types supported by the TomTom Search API. Use it to discover which POICategory values are available, to search categories by name or synonym, or to build category pickers in your UI.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { getPOICategories, getPOICategoryCodes } from '@tomtom-org/maps-sdk/services';
import { API_KEY } from './config';

TomTomConfig.instance.put({ apiKey: API_KEY });

(async () => {
    // 1. Fetch all available categories
    const { poiCategories: all } = await getPOICategories();
    console.log(`Total categories: ${all.length}`);

    // 2. Filter by keyword — served from the same cache, no extra API call
    const { poiCategories: gyms } = await getPOICategories({ language: 'es-ES', filters: ['gimnasio'] });
    console.log('\nLocalized categories:');
    gyms.forEach((category) => console.log(`  ${category.name} (${category.code})`));

    // 3. Get just the codes — useful for passing directly to search() or POIsModule.configure()
    const multiCategoryCodes = await getPOICategoryCodes({ filters: ['metro', 'parking'] });
    console.log(`\nMulti category codes: ${multiCategoryCodes.join(', ')}`);
})();

The returned code values serve two purposes:

Search filtering — pass to search({ poiCategories }) to filter results by category.
Map POI icon filtering — pass generic parent codes (e.g. 'RESTAURANT') to POIsModule.filterCategories() to show or hide the map’s built-in POI icons. Overly specific child codes (e.g. 'ITALIAN_RESTAURANT') are not supported at the map display layer; use a parent code or a POICategoryGroup instead.

Results are cached in memory per language — the first call for a given language fetches from the API; all subsequent calls are served from the cache without a network request.

Basic Usage

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

3
const { poiCategories: categories } = await getPOICategories();
4

5
categories.forEach(category => {
6
    console.log(category.name);               // e.g. "Sports Center"
7
    console.log(category.code);               // e.g. "SPORTS_CENTER"
8
    console.log(category.synonyms);           // e.g. ["Fitness Center", "Gym", "Health Club"]
9
    console.log(category.childCategoryCodes); // e.g. ["FITNESS_CENTER", "GYM"]
10
});

Getting Codes Directly — `getPOICategoryCodes`

Use getPOICategoryCodes when you only need the code values without the full category objects. It accepts the same parameters as getPOICategories.

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

3
// All codes
4
const all = await getPOICategoryCodes();
5

6
// Codes matching a keyword
7
const restaurantCodes = await getPOICategoryCodes({ filters: ['restaurant'] });
8
// e.g. ['RESTAURANT', 'FAST_FOOD', 'CAFE_PUB', ...]
9

10
// Pass directly to search
11
const results = await search({
12
    poiCategories: restaurantCodes,
13
    position: [4.9041, 52.3676],
14
});

Fetching in a Specific Language

Pass language to receive localized category names and synonyms. The result is cached separately per language tag.

1
const { poiCategories: categories } = await getPOICategories({ language: 'fr-FR' });
2

3
categories.forEach(category => {
4
    console.log(category.name);     // Localized name, e.g. "Centre sportif"
5
    console.log(category.synonyms); // Localized synonyms
6
});

Filtering Categories

Use the filters parameter to narrow results client-side. Each filter string is normalized (lowercased, spaces removed) and matched against the normalized form of every name and synonym. A category matches when any of its normalized texts contains the normalized filter as a substring.

For example, 'eat' matches a synonym like 'Eating Out' (normalized: 'eatingout'), and 'italian restaurant' (normalized: 'italianrestaurant') matches 'Italian Restaurant' but not 'Mexican Restaurant'.

No additional API call is made: the filter runs against the in-memory text index built when the cache is first populated. When a parent category matches, its child categories are omitted from the results — the parent already implies them.

1
// Find categories matching "gym"
2
const { poiCategories: gymCategories } = await getPOICategories({ filters: ['gym'] });
3

4
// Multiple filters — results are merged and deduplicated
5
const { poiCategories: combined } = await getPOICategories({ filters: ['gym', 'parking'] });
6

7
// Combine with language
8
const { poiCategories: restaurants } = await getPOICategories({
9
    language: 'en-GB',
10
    filters: ['restaurant'],
11
});

Using Categories in Search

Pass code values directly to the search service to filter results by category:

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

3
// 1. Fetch categories to populate a UI dropdown
4
const { poiCategories: allCategories } = await getPOICategories();
5
const options = allCategories
6
    .map(category => ({ label: category.name, value: category.code }));
7

8
// 2. Search using the selected category
9
const results = await search({
10
    poiCategories: ['SPORTS_CENTER'],
11
    position: [4.9041, 52.3676],
12
    limit: 20,
13
});

Filtering the Map’s Built-in POI Icons

Generic parent codes returned by this service can also be passed to POIsModule.filterCategories() to control which built-in POI icons appear on the map. POICategoryGroup values (e.g. 'FOOD_DRINKS_GROUP') work too.

Note: Overly specific child codes like 'ITALIAN_RESTAURANT' are not supported at the map display layer. Use the parent code 'RESTAURANT' or a group like 'FOOD_DRINKS_GROUP' instead.

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

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

7
// Show only restaurants and sports centres on the map
8
const codes = await getPOICategoryCodes({ filters: ['restaurant', 'sport'] });
9
poisModule.filterCategories({ show: 'only', values: codes });
10

11
// Or use a group to show all food & drink icons
12
poisModule.filterCategories({ show: 'only', values: ['FOOD_DRINKS_GROUP'] });

Exploring Sub-categories

childCategoryCodes lists sub-categories, useful for building drill-down category navigation:

1
const { poiCategories: categories } = await getPOICategories();
2

3
const restaurant = categories.find(category => category.code === 'RESTAURANT');
4
console.log(restaurant?.childCategoryCodes);
5
// e.g. ['ITALIAN_RESTAURANT', 'FRENCH_RESTAURANT', 'AMERICAN_RESTAURANT', ...]
6

7
// Search specifically for the sub-category
8
const results = await search({
9
    poiCategories: ['ITALIAN_RESTAURANT'],
10
    position: [4.9041, 52.3676],
11
});

Cache Management

The cache is populated automatically on first use and persists for the lifetime of the page or process. To fetch categories in a different language, pass language explicitly — each language tag has its own independent cache entry.

1
// Fetches once per language; subsequent calls are served from cache
2
const { poiCategories: english } = await getPOICategories({ language: 'en-GB' });
3
const { poiCategories: french } = await getPOICategories({ language: 'fr-FR' });

Parameter Reference

Parameter	Type	Description
`language`	`string`	IETF language tag for localized names and synonyms (e.g. `'en-GB'`, `'fr-FR'`). Falls back to the global `TomTomConfig` language if not set.
`filters`	`string[]`	Filter strings applied client-side. Each string is normalized (lowercased, spaces removed) and matched as a substring against the normalized form of every `name` and synonym. Results from all strings are merged and deduplicated. Omit to return all categories.

Response Reference

Each entry in the returned poiCategories array has the following shape:

Field	Type	Description
`code`	`POICategory`	Category enum value. Use in `search({ poiCategories })` or, for generic parent codes, in `POIsModule.filterCategories()`.
`name`	`string`	Human-readable category name in the requested language.
`childCategoryCodes`	`POICategory[]`	Sub-category enum values.
`synonyms`	`string[]`	Alternative names in the requested language.

Search — Use POICategory codes from getPOICategories in the poiCategories search parameter to filter search results.
POIs Module — Filter the map’s built-in POI icons using generic POICategory codes or POICategoryGroup values.