Discover places (fuzzy/geometry/along-route)

discoverPlaces() is the one search function. Its parameters pick which of three searches runs:

There is no separate export per search. Each returns places as a GeoJSON FeatureCollection that the Places module shows as it is.

Available search types

Fuzzy search

Fuzzy search tolerates typos, partial input and natural-language phrasing, for POIs and addresses alike:

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

3
const results = await discoverPlaces({
4
    query: 'coffe shop near dam square',
5
    geoBias: { position: [4.9041, 52.3676] },
6
});
7

8
// A query string on its own runs a fuzzy search, the same as `{ query }`
9
const museums = await discoverPlaces('museums in amsterdam');

Only fuzzy search takes geoBias, cursor, typeahead, minFuzzyLevel, maxFuzzyLevel and filters.countries. See Fuzzy search parameters.

Geometry search

Geometry search finds places inside one or more areas:

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

3
const inCircle = await discoverPlaces({
4
    query: 'restaurants',
5
    geometries: [{ type: 'Circle', coordinates: [4.9041, 52.3676], radius: 5000 }], // radius in metres
6
});
7

8
const inPolygon = await discoverPlaces({
9
    query: 'museums',
10
    geometries: [{
11
        type: 'Polygon',
12
        coordinates: [[[4.7, 52.2], [5.1, 52.2], [5.1, 52.5], [4.7, 52.5], [4.7, 52.2]]],
13
    }],
14
});

• geometries takes a Circle (coordinates plus radius in metres, an SDK extension to GeoJSON), a Polygon, a MultiPolygon or a polygon FeatureCollection such as a geometryData result, passed as it is. You can mix several in one array.
• Only a polygon’s outer ring is sent to the API, so holes are ignored. The ring is sampled down to 50 vertices, and a MultiPolygon of more than 50 polygons keeps its 50 largest.

Along-route search

Along-route search finds places reachable within maxDetourTimeSeconds of a route, such as fuel stops, cafés or EV chargers:

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

3
const routes = await calculateRoute({ locations: [[4.9041, 52.3676], [5.1214, 52.0907]] });
4

5
const chargers = await discoverPlaces({
6
    route: routes.features[0],
7
    maxDetourTimeSeconds: 600,
8
    filters: { poiCategories: ['CHARGING_LOCATION'] },
9
    limit: 10,
10
});
11

12
const cafes = await discoverPlaces({
13
    route: [[4.9, 52.37], [4.95, 52.28], [5.1, 52.09]], // or a GeoJSON LineString
14
    maxDetourTimeSeconds: 300,
15
    query: 'cafe',
16
    sortBy: 'detourOffset',
17
});

Give it a query, a filter or both, as validation rejects an along-route search with neither. indexes narrows a search but doesn’t count as a filter here.

Along-route results carry detourTimeInSeconds and detourDistanceInMeters, and either can be negative. A negative detour means the route through the place is faster or shorter than the original one. Results sorted by 'detourOffset' also carry detourOffsetInMeters, the distance from the start of the route to where the detour leaves it. The properties type is AlongRoutePlaceProps.

1
const minutes = Math.round(chargers.features[0].properties.detourTimeInSeconds / 60);

The Node.js along-route search example finds fast chargers within a one-minute detour of a route and prints each detour.

Search as you type

For a search box, use getSearchSuggestions(). One call returns places with brand and category suggestions.

Parameter reference

The full type is DiscoverPlacesParams. An option of another search variant, such as cursor beside geometries or geoBias beside route, is a compile error. It isn’t silently dropped.

Common parameters

All three searches take these, plus the options every service call takes (language, signal, validateRequest), covered in Request options and errors:

Filters

Every option that drops results lives under filters. geoBias stays separate. It sets where to look, not what to accept.

• A filter excludes. A place that doesn’t match is dropped, not ranked lower.
• Values within one member are OR’d, and members are AND’d. poiBrands: ['Shell', 'BP'] with fuelTypes: ['Diesel'] keeps stations of either brand that sell diesel.
• The type follows the search. Fuzzy search takes SearchFilters (PlaceFilters & GeographicFilters). Geometry and along-route search take PlaceFilters, so filters.countries beside geometries or route is a compile error. Geocoding takes countries and geographyTypes.

1
import { discoverPlaces } from '@tomtom-org/maps-sdk/services';
2
import type { SearchFilters } from '@tomtom-org/maps-sdk/services';
3

4
const dieselStations: SearchFilters = {
5
    countries: ['NL', 'BE'],
6
    poiBrands: ['Shell', 'BP'],
7
    fuelTypes: ['Diesel'],
8
};
9

10
const results = await discoverPlaces({
11
    filters: dieselStations,
12
    geoBias: { position: [4.9041, 52.3676], radiusMeters: 20000 },
13
});

In the demo below, the same fuel station search runs once with a brand, once with a fuel type and once with a country filter, each result set in its own colour:

Geographic bias

Fuzzy search and geocoding take one geoBias, either a point or a rectangle. The compiler rejects both together, and a call that passes both anyway rejects with an INVALID_REQUEST error.

1
// Around a point: ranks nearer results higher; with radiusMeters, also confines results to the circle
2
geoBias: { position: [4.9041, 52.3676], radiusMeters: 2000 }
3

4
// Inside a rectangle: [west, south, east, north], or any GeoJSON a bbox derives from
5
geoBias: { boundingBox: map.getBBox() }

• position takes [longitude, latitude] or any GeoJSON carrying one.
• Omit geoBias to search without a geographic bias.
• Geometry and along-route search take none, because their geometries or route is the search area.

Fuzzy search parameters

On top of the common parameters:

Geometry search parameters

On top of the common parameters:

Along-route search parameters

On top of the common parameters:

POI categories

filters.poiCategories takes POICategory codes, such as ITALIAN_RESTAURANT, FUEL_STATION, HOTEL, PHARMACY, PARKING_GARAGE or CHARGING_LOCATION. The POI categories service lists them and finds them by name or synonym.

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

3
const geoBias = { position: [4.9041, 52.3676], radiusMeters: 1000 };
4

5
const italian = await discoverPlaces({ geoBias, filters: { poiCategories: ['ITALIAN_RESTAURANT'] } });
6

7
// Codes looked up by keyword first
8
const restaurantCodes = await getPOICategoryCodes({ filters: ['restaurant'] });
9
const restaurants = await discoverPlaces({ geoBias, filters: { poiCategories: restaurantCodes } });
10

11
// Or named in words, in one call
12
const sushi = await discoverPlaces({ geoBias, filters: { poiCategoryQuery: 'sushi' } });
13

14
// EV charging, by connector and power
15
const fastChargers = await discoverPlaces({
16
    geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 },
17
    filters: { poiCategories: ['CHARGING_LOCATION'], connectors: ['IEC62196Type2CCS', 'Tesla'], minPowerKW: 50 },
18
});

A parent code also returns its sub-categories, the codes in its childCategoryCodes. For example, 'SCHOOL' also returns CHILDCARE and DRIVING_SCHOOL places. To leave them out, list only the codes you want, such as 'SCHOOL_GENERIC' for a plain school and 'PRIMARY_SCHOOL'. A place filed under the parent alone comes back only with the parent code. To keep those too, or when your list would pass the 10 codes a search takes, search by the parent and keep the results whose poi.categories holds the parent code or one you want.

Naming the category in words: poiCategoryQuery

filters.poiCategoryQuery takes categories as a person says them, such as 'sushi' or ['gym', 'parking'], and searches the POI categories they name. Every search variant takes it, whether near a geoBias, inside geometries or along a route.

• The words go through resolvePOICategories in the call’s language, and the codes it returns become the search’s poiCategories. For a language the categories lack, such as hi-IN or ja-JP, the words match the English names.
• The category list costs one request per language and session, and is then cached.
• An unmatched word is left out. If no word matches, the call rejects with an SDKError and sends no search. To handle unmatched words yourself, call resolvePOICategories first.
• When the user names a kind of place, prefer it to query: 'sushi', because query also matches names and addresses.

For a category the user picks while typing, search suggestions return it as a category suggestion whose refine() filters on its code, with no lookup.

In the demo below, a word in the chosen language searches its category inside the Paris outline:

Working with search results

Each feature is a Place with SearchPlaceProps. Places describes every property, including the search-specific ones.

1
const results = await discoverPlaces({ query: 'coffee', geoBias: { position: [4.9041, 52.3676] } });
2

3
results.features.forEach((place) => {
4
    console.log(place.properties.poi?.name);               // POI results only
5
    console.log(place.properties.address.freeformAddress);
6
    console.log(place.geometry.coordinates);               // [longitude, latitude]
7
    console.log(place.properties.poi?.categories);         // POICategory[], e.g. ['CAFE_PUB']
8
    console.log(place.properties.poi?.localizedCategories); // string[] in English, whatever the call's language
9
    console.log(place.properties.distance);                // metres from geoBias.position, when given
10
});

discoverOnePlace() returns the first fuzzy-search result, and throws an SDKError with the code NOT_FOUND when there is none:

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

3
const place = await discoverOnePlace('Eiffel Tower');
4

5
// The params form takes the fuzzy search parameters except `limit`
6
const nearby = await discoverOnePlace({ query: 'coffee', geoBias: { position: [2.2945, 48.8584] } });

Pagination

A fuzzy search response carries nextCursor in its properties while a next page exists. Pass it back as cursor, with the same parameters:

1
let response = await discoverPlaces({ query: 'cafe', limit: 20 });
2
const all = [...response.features];
3

4
while (response.properties?.nextCursor) {
5
    response = await discoverPlaces({ query: 'cafe', limit: 20, cursor: response.properties?.nextCursor });
6
    all.push(...response.features);
7
}

The loop spends a request per page up front. To fetch one page per Load more click instead, keep the request and the last nextCursor between clicks, as the search playground does:

1
import { discoverPlaces } from '@tomtom-org/maps-sdk/services';
2
import type { FuzzySearchParams } from '@tomtom-org/maps-sdk/services';
3

4
const request: FuzzySearchParams = { query: 'cafe', geoBias: { position: [4.9041, 52.3676] }, limit: 20 };
5
let nextCursor: string | undefined;
6

7
const loadPage = async (cursor?: string) => {
8
    loadMoreButton.disabled = true; // a second click before the page lands would fetch it twice
9
    const page = await discoverPlaces({ ...request, cursor });
10
    appendToResultList(page.features);
11
    nextCursor = page.properties?.nextCursor;
12
    loadMoreButton.disabled = !nextCursor;
13
};
14

15
await loadPage();
16
loadMoreButton.onclick = () => loadPage(nextCursor);

• The cursor is opaque. Pass it back unchanged. Its contents aren’t part of the contract. A value the SDK can’t read as a cursor throws an SDKError.
• A cursor continues one search, but the SDK doesn’t check which one. If you pass it with a new query or different filters, that search skips its first pages. Leave cursor out to start a new search.
• nextCursor, not totalResults, tells whether a next page exists. It is absent once the next page would start at totalResults, after an empty page, and once the next page would start past result 1900, the furthest the backend serves. Fuzzy search’s totalResults is at most 100, and lower at a larger limit, so its pagination ends there.
• Only fuzzy search and geocoding paginate. Geometry and along-route search return one page, with no nextCursor. geocode pages the same way.

Fields that may be absent

The type is the contract. Where a property is optional, handle its absence instead of assuming a value.

Geocoding counts matches beyond the page it returns. To show that count, guard totalResults first:

1
const results = await geocode({ query: 'Main Street', limit: 10 });
2

3
if (results.properties?.totalResults !== undefined) {
4
    const { numResults, totalResults } = results.properties;
5
    console.log(`Showing ${numResults} of ${totalResults}`);
6
}

A missing fuzzyLevel means “not reported”, not “matched exactly”, so don’t read it as 0.

Examples

Find bus stops in an area (Node.js)

A category search confined to a rectangle, as in the Node.js POI search example:

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

3
const results = await discoverPlaces({
4
    filters: { poiCategories: ['BUS_STOP'] },
5
    geoBias: { boundingBox: [4.72, 52.27, 5.07, 52.43] }, // [west, south, east, north]
6
    limit: 100,
7
});
8

9
results.features.forEach((stop) => {
10
    const [lng, lat] = stop.geometry.coordinates;
11
    console.log(`${stop.properties.poi?.name} — ${lng}, ${lat}`);
12
});

Integration with map visualization

The Places module shows a search response without mapping fields first:

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

4
const map = new TomTomMap({ mapLibre: { container: 'map' } });
5
const placesModule = await PlacesModule.create(map);
6

7
await placesModule.show(await discoverPlaces({ query: 'museums', geoBias: { position: [4.9041, 52.3676] } }));

Searching again as the map moves

A search re-run on every map move can answer out of order. A slow answer for the previous viewport then paints over the current one. To prevent this, run it through createLatestRequest, as the places customization playground does:

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

3
const latestSearch = createLatestRequest();
4

5
map.mapLibreMap.on('moveend', async () => {
6
    const search = await latestSearch.run((signal) =>
7
        discoverPlaces({
8
            filters: { poiCategories: ['CAFE_PUB'] },
9
            geoBias: { boundingBox: map.getBBox() },
10
            signal,
11
        })
12
    );
13
    if (search.current) await placesModule.show(search.value);
14
});

To keep POI categories on the map as it moves without writing this yourself, use the viewport places plugin.

Related guides and examples

Map integration

• Places module - Search results as interactive places on the map
• POIs - The map’s own POI icons, filtered by the same categories

Related examples

• Along route search - Beaches and viewpoints within a one-minute detour of a drive
• Along route search (Node.js) - Fast chargers along a route, in Node.js
• Along route search playground - A query and POI categories along a route
• Geometry searches along a route - Corridors of different widths around a route, as polygons
• EV chargers nearby - Fast chargers filtered by connectors and minPowerKW, with a clicked station’s connectors
• Geometry search playground - Searching inside area boundaries
• Geometry search (Node.js) - Cafés inside a polygon, in Node.js
• Places by category in words - A category named in words, in five languages, inside a city outline
• Search filters - The same fuel station search run once per filter: brand, fuel type and country
• Search playground - Search-as-you-type, and a picked brand or category paged in with nextCursor
• Search places in geometry - Places inside the outline of a geocoded area
• Search places nearby location - Places around a geocoded location
• Places customization playground - Customizing how search results look

Related services

• Geocoding - Addresses to coordinates
• Reverse geocoding - Coordinates to an address
• Geometry data - The outlines a geometry search can run inside