POI categories

getPOICategories() returns every POI category the Search API knows, with its names and synonyms in a language. Use it to build a category picker, or to find categories by name or synonym. Each category's code is a POICategory:

• Search filtering — discoverPlaces({ filters: { poiCategories } }).
• The map's own POI icons — the POIsModule filters.categories setting, for generic parent codes only; see Filtering the map's built-in POI icons.

Basic usage

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

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

categories.forEach((category) => {
    console.log(category.name);               // e.g. "Sports Center"
    console.log(category.code);               // e.g. "SPORTS_CENTER"
    console.log(category.synonyms);           // e.g. ["Sports Centre"]
    console.log(category.childCategoryCodes); // e.g. ["FITNESS_CLUB_AND_CENTER", "HORSE_RIDING", ...]
});

Getting codes directly — getPOICategoryCodes

getPOICategoryCodes takes the same parameters and returns the codes alone:

import { discoverPlaces, getPOICategoryCodes } from '@tomtom-org/maps-sdk/services';

const all = await getPOICategoryCodes();

// Codes matching a keyword, best match first, e.g. ['RESTAURANT', 'RESTAURANT_AREA']
const restaurantCodes = await getPOICategoryCodes({ filters: ['restaurant'] });

const results = await discoverPlaces({
    filters: { poiCategories: restaurantCodes },
    geoBias: { position: [4.9041, 52.3676] },
});

Fetching in a specific language

language localizes the names and synonyms, and falls back to the global language:

const { poiCategories: categories } = await getPOICategories({ language: 'fr-FR' });
console.log(categories[0].name); // e.g. "Centre sportif"

Filtering categories

filters finds categories by keyword, client-side, against the cached list: no request beyond the first. Each filter ranks the categories it matches, strongest first:

1. A category code, such as 'CAFE', matches that category only.
2. Any other filter ranks an exact name or synonym first, then a name or synonym the filter starts ('parking' finds 'Parking Garage'), then one holding it as a later word, and last one holding it as a substring.

• Close to the best only. A filter keeps the matches ranking close to its best one, so 'bar' finds 'Bar' but not 'Nail Salon' through its synonym 'Nail Bar'.
• Normalized. Case, accents and punctuation are ignored, and spaces too when matching a substring: 'cafe' finds 'Café', and 'bookstore' finds 'Book Shop' through its synonym 'Book Store'. A blank filter matches nothing.
• Several filters merge round-robin, so each filter's best match comes first, with one entry per code. A category ranking below its matched parent is left out, as the parent already covers it.

const { poiCategories: gymCategories } = await getPOICategories({ filters: ['gym'] });

// Each filter's best match first, one entry per code
const { poiCategories: combined } = await getPOICategories({ filters: ['gym', 'parking'] });

const { poiCategories: restaurants } = await getPOICategories({ language: 'en-GB', filters: ['restaurant'] });

Using categories in search

Pass code values to discoverPlaces(), such as the one picked from a dropdown:

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

const { poiCategories: allCategories } = await getPOICategories();
const options = allCategories.map((category) => ({ label: category.name, value: category.code }));

const results = await discoverPlaces({
    filters: { poiCategories: ['SPORTS_CENTER'] },
    geoBias: { position: [4.9041, 52.3676] },
    limit: 20,
});

When the category arrives as a word rather than a pick from a list, skip the lookup and pass it as filters.poiCategoryQuery, which resolves it with resolvePOICategories:

const gyms = await discoverPlaces({ filters: { poiCategoryQuery: 'gym' }, geoBias: { position: [4.9041, 52.3676] } });

Resolving words for a search — resolvePOICategories

resolvePOICategories turns words, or codes, into the poiCategories of one search, and reports the words that match nothing. Call it before searching to decide about those words yourself: search with the rest, ask the user, or fall back to a free-text query.

import { discoverPlaces, resolvePOICategories } from '@tomtom-org/maps-sdk/services';

const { poiCategories, unmatched } = await resolvePOICategories({ filters: ['café', 'PHARMACY', 'xyzzy'] });
// unmatched: ['xyzzy']

if (poiCategories.length) {
    const places = await discoverPlaces({ filters: { poiCategories }, geoBias: { position: [4.9041, 52.3676] } });
}

• Matching: each filter matches as in Filtering categories, so a code stays itself.
• Codes kept: each filter's best three, merged round-robin and capped at the 10 a search accepts.
• Same rules as the search: filters.poiCategoryQuery runs this lookup, so both resolve a word the same way.
• Codes alone skip the catalogue request and come back deduplicated.
• Which to call: resolvePOICategories builds one search; getPOICategoryCodes lists every close match, for a picker or the map's POI icons.

Filtering the map's built-in POI icons

Generic parent codes, and POICategoryGroup values such as 'FOOD_DRINKS_GROUP', set as the POIsModule filters.categories setting choose which of the map's own POI icons show. Specific child codes such as 'ITALIAN_RESTAURANT' are not supported there: use the parent 'RESTAURANT' or a group. The POIs module guide covers the setting and its groups.

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

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

const codes = await getPOICategoryCodes({ filters: ['restaurant', 'sports center'] });
poisModule.updateConfig({ filters: { categories: { show: 'only', values: codes } } });

Exploring sub-categories

childCategoryCodes lists a category's sub-categories, for drill-down navigation:

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

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

Cache management

• One request per language. The first call in a language fetches the list; every later call in it, filtered or not, resolvePOICategories and filters.poiCategoryQuery included, reads the cache.
• In memory, for the lifetime of the page or process. There is nothing to clear.

const { poiCategories: english } = await getPOICategories({ language: 'en-GB' });
const { poiCategories: french } = await getPOICategories({ language: 'fr-FR' }); // a second request

Parameter reference

On top of the options every service call takes:

Response reference

Each entry of poiCategories:

resolvePOICategories returns { poiCategories, unmatched } instead: the codes for one search, best first, and the filters nothing matched, as given.

Related guides

• Discover places — Searching by category code or by category in words
• POIs module — The map's own POI icons, filtered by parent codes or groups
• Search suggestions — A category the user is typing, as a category suggestion