Discover places (fuzzy/geometry/along-route)

The TomTom Maps SDK provides three powerful search services that help you find places, addresses, and points of interest with different search strategies optimized for various use cases. Each search type is designed to handle specific user interaction patterns and application requirements.

Available search types

Fuzzy search

Comprehensive search that handles typos, variations in queries, and natural language input. Fuzzy search is robust and forgiving, making it ideal for situations where users might not know exact spellings or when dealing with international locations.

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

const results = await discoverPlaces({
    query: 'coffe shop near dam square',  // Handles typos and variations
    geoBias: { position: [4.9041, 52.3676] },
});

Advanced Capabilities:

• Tolerates spelling mistakes and variations in input
• Supports natural language queries for intuitive user interaction
• Category and POI search with intelligent matching
• Flexible radius-based or bounding box search options

Ideal Applications:

• General search functionality where user input quality varies
• International applications with diverse language inputs
• Voice-to-text search implementations

Geometry search

Find places within specific geographic boundaries or custom areas. Geometry search enables location discovery within precisely defined regions, making it perfect for area-specific applications and location-based services.

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

// Search within a circle
const results = await discoverPlaces({
    query: 'restaurants',
    geometries: [{
        type: 'Circle',
        coordinates: [4.9041, 52.3676], // [longitude, latitude]
        radius: 5000                     // meters
    }]
});

// Search within a GeoJSON polygon
const results = await discoverPlaces({
    query: 'museums',
    geometries: [{
        type: 'Polygon',
        coordinates: [[[4.7, 52.2], [5.1, 52.2], [5.1, 52.5], [4.7, 52.5], [4.7, 52.2]]]
    }]
});

The discoverPlaces() function automatically dispatches to geometry search when geometries is provided, and to fuzzy search otherwise.

Geometric Search Options:

• Circle: Custom radius around a point (type: 'Circle', coordinates, radius)
• Polygon: GeoJSON polygon for custom area boundaries
• MultiPolygon: Multiple non-contiguous areas in a single query

Perfect For:

• Location discovery within specific neighborhoods or districts
• Delivery and service area applications
• Tourism and local business discovery

Along-route search

Discover places of interest along a planned route, filtered to a maximum detour time. Along-route search is ideal for trip planning scenarios where users want to find fuel stops, restaurants, or EV charging stations without significantly deviating from their journey.

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

// Pass a GeoJSON LineString directly
const results = await discoverPlaces({
    route: {
        type: 'LineString',
        coordinates: [
            [4.9, 52.37],  // Amsterdam [longitude, latitude]
            [4.95, 52.28],
            [5.0, 52.15],
            [5.1, 52.09],  // Utrecht
        ]
    },
    maxDetourTimeSeconds: 600,
    poiCategories: ['CHARGING_LOCATION'],
    limit: 10,
});

// Or pass a Route Feature returned by calculateRoute
import { calculateRoute } from '@tomtom-org/maps-sdk/services';

const routes = await calculateRoute({ locations: [amsterdamWaypoint, utrechtWaypoint] });
const results = await discoverPlaces({
    route: routes.features[0],
    maxDetourTimeSeconds: 600,
    query: 'cafe',
});

The discoverPlaces() function dispatches to along-route search when a route is provided.

Key Features:

• Detour-time filtering — only surfaces places reachable within the allowed detour
• Flexible route input — accepts a LineString, Position[], or a Route Feature from calculateRoute
• Category and text search — combine poiCategories and query as needed
• Sort control — order results by detour time or position along the route

Ideal Applications:

• EV trip planning with charging stop discovery
• Road-trip itinerary building
• Fleet routing with service stop optimization

Search as you type

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

Parameter reference

Common parameters

These parameters apply to fuzzy search, geometry search, and along-route search:

Fuzzy search parameters

Geographic bias

Search and geocoding take a single geoBias option, which is either a point or a rectangle — the two cannot be combined, so the compiler rejects passing both:

// Around a point: biases ranking, and confines results when radiusMeters is given
geoBias: { position: [4.9041, 52.3676], radiusMeters: 2000 }

// Inside a rectangle: [minLng, minLat, maxLng, maxLat], or any GeoJSON a bbox derives from
geoBias: { boundingBox: map.getBBox() }

Omit geoBias entirely to search without a geographic bias.

In addition to all common parameters, fuzzy search supports:

Geometry search parameters

In addition to all common parameters, geometry search requires:

Note: Geometry search does not support geoBias. The geometry shapes define the search area.

Along-route search parameters

Along-route search requires route and maxDetourTimeSeconds. All common parameters also apply. geoBias is not available — the route geometry defines where to search. Parameters from fuzzy/geometry search such as geometries and offset also do not apply.

POI categories

Use poiCategories to filter results to specific types of places. Each value must be a POICategory enum constant. Use the getPOICategories service to search and browse available categories by name or synonym, then pass the resulting code values directly here.

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

// Filter to a known category
const italian = await discoverPlaces({
    geoBias: { position: [4.9041, 52.3676], radiusMeters: 1000 },
    poiCategories: ['ITALIAN_RESTAURANT']
});

// Discover categories first, then search
const restaurantCodes = await getPOICategoryCodes({ filters: ['restaurant'] });
const restaurants = await discoverPlaces({
    geoBias: { position: [4.9041, 52.3676], radiusMeters: 1000 },
    poiCategories: restaurantCodes
});

// EV charging with connector and power filtering
const evChargers = await discoverPlaces({
    geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 },
    poiCategories: ['CHARGING_LOCATION'],
    connectors: ['IEC62196Type2CCS', 'Tesla'],
    minPowerKW: 50
});

Example category values: ITALIAN_RESTAURANT, FUEL_STATION, HOTEL, PHARMACY, MUSEUM, PARKING_GARAGE, CHARGING_LOCATION, MALL. See the POICategory type for the full list, or use the getPOICategories service to search and explore them at runtime.

Working with search results

Search results follow a GeoJSON FeatureCollection structure. Each feature is a GeoJSON Feature<Point> with place data in properties:

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

results.features.forEach(place => {
    console.log(place.properties.poi?.name);              // Business name (POI results)
    console.log(place.properties.address.freeformAddress);// Formatted address
    console.log(place.geometry.coordinates);              // [longitude, latitude]
    console.log(place.properties.poi?.categories);        // POICategory[] (e.g. ['CAFE'])
    console.log(place.properties.poi?.localizedCategories); // string[] (e.g. ['café'])
    console.log(place.properties.score);                  // Relevance score
    console.log(place.properties.distance);               // Distance in meters (if position was given)
});

To retrieve only the first result, use discoverOnePlace() — it throws if no results are found:

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

const place = await discoverOnePlace('Eiffel Tower');
console.log(place.properties.poi?.name); // 'Eiffel Tower'

// The params form takes everything `discoverPlaces` does except `limit`
const nearby = await discoverOnePlace({ query: 'coffee', geoBias: { position: [2.2945, 48.8584] } });

Fields that may be absent

A few result and summary fields are not guaranteed. The type is the contract: where a property is optional, handle its absence rather than assuming a value.

The pattern to follow — guard, then use:

const results = await discoverPlaces({ query: 'pizza', limit: 10 });
const { offset, numResults, totalResults } = results.properties;

if (totalResults !== undefined && offset + numResults < totalResults) {
    // more pages available; fetch with offset: offset + numResults
}

Treating fuzzyLevel as 0 when it is missing is the one to avoid: absent means "not reported", not "matched exactly".

Examples

Find bus stops in an area (Node.js)

Use geoBias: { boundingBox } to search for all bus stops within a rectangular geographic area. This example searches the Amsterdam city area:

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

const results = await discoverPlaces({
    poiCategories: ['BUS_STOP'],
    geoBias: { boundingBox: [4.72, 52.27, 5.07, 52.43] }, // [minLng, minLat, maxLng, maxLat]
    limit: 100
});

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

Integration with map visualization

Search results can be directly integrated with the TomTom Maps SDK for immediate visual representation:

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

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

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

// Display search results as markers on the map
await placesModule.show(results);

Performance optimization

For optimal performance in production applications, consider these best practices:

Search Strategy Selection:

• Use getSearchSuggestions() for search boxes
• Use fuzzy search for comprehensive location finding
• Use geometry search for area-specific discovery

Result Limiting:

• Set appropriate limit values based on UI requirements
• Use offset for pagination of large result sets
• Cache frequent search results for faster response times

For complete search implementation examples and advanced usage patterns, go to the examples gallery.

Related guides and examples

Map integration

• Places Module - Display search results as interactive places on the map with customizable styling and user interactions
• POIs - Advanced point-of-interest visualization and filtering for search results

Related examples

• Along Route Search (Node.js) - Find EV charging stations along a planned route using Node.js
• Along Route Search Playground - Interactive along-route search with query input and POI category checkboxes
• Search playground - Real-time search-as-you-type with instant map updates
• Geometry Search Playground - Search within custom geographic boundaries and areas
• Geometry Search with POI Categories - Category-filtered search within specific regions
• Places customization playground - Customizing the appearance and behavior of search result markers
• Search Places in Geometry - Specialized search example for finding places in a defined area
• Search Places nearby Location - Specialized search example for finding places nearby a location

Related services

• Geocoding - Convert search result addresses to precise coordinates for enhanced accuracy
• Reverse Geocoding - Get address information for search result coordinates