Search (autocomplete/fuzzy/geometry search)

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.

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

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

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.

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

3
// Search within a circle
4
const results = await search({
5
    query: 'restaurants',
6
    geometries: [{
7
        type: 'Circle',
8
        coordinates: [4.9041, 52.3676], // [longitude, latitude]
9
        radius: 5000                     // meters
10
    }]
11
});
12

13
// Search within a GeoJSON polygon
14
const results = await search({
15
    query: 'museums',
16
    geometries: [{
17
        type: 'Polygon',
18
        coordinates: [[[4.7, 52.2], [5.1, 52.2], [5.1, 52.5], [4.7, 52.5], [4.7, 52.2]]]
19
    }]
20
});

The search() 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

Autocomplete Search

Perfect for search-as-you-type experiences with instant suggestions, autocomplete search provides real-time results as users type their queries. This service is optimized for speed and relevance, making it ideal for interactive search interfaces.

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

3
const suggestions = await autocompleteSearch({
4
    query: 'coffee',
5
    position: [4.9041, 52.3676], // Amsterdam
6
    resultType: ['category', 'brand', 'plaintext']
7
});

Key Features:

• Real-time suggestions as users type with minimal latency
• Brand and category suggestions for enhanced user experience
• Optimized for speed with lightweight responses
• Perfect for search bars and interactive input fields

Parameter Reference

Common Parameters

These parameters apply to both fuzzy search and geometry search:

Fuzzy Search Parameters

In addition to all common parameters, fuzzy search supports:

Geometry Search Parameters

In addition to all common parameters, geometry search requires:

Autocomplete Search Parameters

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.

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

3
// Filter to a known category
4
const italian = await search({
5
    position: [4.9041, 52.3676],
6
    radiusMeters: 1000,
7
    poiCategories: ['ITALIAN_RESTAURANT']
8
});
9

10
// Discover categories first, then search
11
const restaurantCodes = await getPOICategoryCodes({ filters: ['restaurant'] });
12
const restaurants = await search({
13
    position: [4.9041, 52.3676],
14
    radiusMeters: 1000,
15
    poiCategories: restaurantCodes
16
});
17

18
// EV charging with connector and power filtering
19
const evChargers = await search({
20
    position: [4.9041, 52.3676],
21
    radiusMeters: 5000,
22
    poiCategories: ['ELECTRIC_VEHICLE_STATION'],
23
    connectors: ['IEC62196Type2CCS', 'Tesla'],
24
    minPowerKW: 50
25
});

Example category values: ITALIAN_RESTAURANT, GAS_STATION, HOTEL, PHARMACY, MUSEUM, PARKING_GARAGE, ELECTRIC_VEHICLE_STATION, SHOPPING_CENTER. 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:

1
const results = await search({
2
    query: 'coffee',
3
    position: [4.9041, 52.3676]
4
});
5

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

To retrieve only the first result, use searchOne():

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

3
const place = await searchOne({ query: 'Eiffel Tower', position: [2.3522, 48.8566] });
4
if (place) {
5
    console.log(place.properties.poi?.name); // 'Eiffel Tower'
6
}

Examples

Find Bus Stops in an Area (Node.js)

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

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

3
const results = await search({
4
    poiCategories: ['BUS_STOP'],
5
    boundingBox: [4.72, 52.27, 5.07, 52.43], // [minLng, minLat, maxLng, maxLat]
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

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

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

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

6
const results = await search({
7
    query: 'museums',
8
    position: [4.9041, 52.3676]
9
});
10

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

Performance Optimization

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

Search Strategy Selection:

• Use autocomplete for real-time search interfaces
• 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 http://docs.tomtom.com/maps-sdk-js/examples .

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

• Fuzzy Search Playground - Interactive fuzzy search with map visualization and result filtering
• Autocomplete Fuzzy 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 Customize - 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