tomtom-fuzzy-search
Perform flexible location-based searches using natural language queries, supporting addresses, POIs, coordinates, and free-text inputs, with customizable filters for language, country, radius, and categories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| addressRanges | No | Include address ranges in the response | |
| brandSet | No | Filter by brand names. Examples: 'Starbucks,Peet\'s', 'Marriott,Hilton'. Use quotes for brands with commas. | |
| btmRight | No | Bottom-right coordinates of bounding box (format: 'lat,lon'). Must be used with topLeft | |
| categorySet | No | Filter by POI categories. Common IDs: '7315' (restaurants), '7309' (gas), '7311' (hotels), '9663' (EV charging). | |
| connectorSet | No | EV connector types: 'IEC62196Type2CableAttached', 'Chademo', 'TeslaConnector' | |
| connectors | No | Include connector information for EV stations | |
| countrySet | No | Limit results to specific countries using ISO codes. Examples: 'US', 'FR,GB', 'CA,US' | |
| entityTypeSet | No | Filter results by entity types | |
| ext | No | Extended parameters for the search | |
| extendedPostalCodesFor | No | Include extended postal codes for specific index types. Examples: 'PAD', 'PAD,Addr', 'POI' | |
| fuelSet | No | Fuel types: 'Petrol', 'Diesel', 'LPG', 'Hydrogen', 'E85' | |
| geometries | No | Include geometries information in the response | |
| gomList | No | Include geometry-only matches in the result list | |
| idxSet | No | Filter results by index set | |
| language | No | Preferred language for results using IETF language tags. Examples: 'en-US', 'fr-FR', 'de-DE', 'es-ES' | |
| lat | No | Center latitude for location bias | |
| limit | No | Maximum number of results to return (1-100). Default: 5 | |
| lon | No | Center longitude for location bias | |
| mapcodes | No | Include mapcode information in the response. Mapcodes represent specific locations within a few meters and are designed to be short, easy to recognize and communicate. Options: Local, International, Alternative. Examples: 'Local' (local mapcode only), 'Local,Alternative' (multiple types). Accepts array of string(s). | |
| maxFuzzyLevel | No | Maximum fuzzy matching level (1-4) | |
| maxPowerKW | No | Maximum charging power in kW for EV stations | |
| minFuzzyLevel | No | Minimum fuzzy matching level (1-4) | |
| minPowerKW | No | Minimum charging power in kW for EV stations | |
| ofs | No | Offset for pagination of results | |
| openingHours | No | List of opening hours for a POI (Points of Interest).Value: `nextSevenDays` Mode shows the opening hours for next week, starting with the current day in the local time of the POI. Usage example: openingHours=nextSevenDays | |
| query | Yes | Natural language search query. Works with addresses, POI names, coordinates, or free-form text. Examples: 'restaurants near Central Park', 'IKEA stores', '52.3791,4.8994', 'coffee shops downtown' | |
| radius | No | Search radius in meters when lat/lon provided. Examples: 1000 (neighborhood), 5000 (city area), 20000 (metro area). | |
| relatedPois | No | Include related points of interest | |
| roadUse | No | Include road usage information | |
| sort | No | Sort options for results | |
| timeZone | No | Used to indicate the mode in which the timeZone object should be returned. Values: iana Mode shows the IANA ID which allows the user to determine the current time zone for the POI. Usage examples: timeZone=iana | |
| topLeft | No | Top-left coordinates of bounding box (format: 'lat,lon'). Must be used with btmRight | |
| typeahead | No | Enable autocomplete mode for partial queries. Use for search-as-you-type interfaces. | |
| vehicleTypeSet | No | A comma-separated list of vehicle types that could be used to restrict the result to the Points Of Interest of specific vehicles. If vehicleTypeSet is specified, the query can remain empty. Only POIs with a proper vehicle type will be returned. Value: A comma-separated list of vehicle type identifiers (in any order). When multiple vehicles types are provided, only POIs that belong to (at least) one of the vehicle types from the provided list will be returned. Available vehicle types: Car , Truck | |
| view | No | Geopolitical view for disputed territories. Options: 'Unified', 'AR', 'IL', 'IN', 'MA', 'PK', 'RU', 'TR', 'CN' |
Implementation Reference
- src/handlers/searchHandler.ts:70-85 (handler)MCP tool handler factory for 'tomtom-fuzzy-search'. Logs the query, calls fuzzySearch service with params, returns JSON-stringified results or error.export function createFuzzySearchHandler() { return async (params: any) => { logger.info(`🔍 Fuzzy search: "${params.query}"`); try { const result = await fuzzySearch(params.query, params); logger.info(`✅ Fuzzy search completed`); return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] }; } catch (error: any) { logger.error(`❌ Fuzzy search failed: ${error.message}`); return { content: [{ type: "text" as const, text: JSON.stringify({ error: error.message }) }], isError: true, }; } }; }
- Core fuzzySearch function that makes the HTTP call to TomTom Fuzzy Search API (/search/2/search/{query}.json) with built parameters, handles errors.export async function fuzzySearch( query: string, options?: ExtendedSearchOptions ): Promise<SearchResult> { const params = buildSearchParams(options, { limit: 10, language: "en-US", }); return makeApiCall( `/search/${API_VERSION.SEARCH}/search/${encodeURIComponent(query)}.json`, params, `Fuzzy searching for: "${query}"` ); }
- Zod schema defining input parameters for tomtom-fuzzy-search tool, including query, location bias, filters, fuzzy levels, etc.export const tomtomFuzzySearchSchema = { query: z .string() .describe( "Natural language search query. Works with addresses, POI names, coordinates, or free-form text. Examples: 'restaurants near Central Park', 'IKEA stores', '52.3791,4.8994', 'coffee shops downtown'" ), ...baseSearchParams, ...locationBiasParams, ...boundingBoxParams, ...poiFilterParams, typeahead: z .boolean() .optional() .describe( "Enable autocomplete mode for partial queries. Use for search-as-you-type interfaces." ), radius: z .number() .optional() .describe( "Search radius in meters when lat/lon provided. Examples: 1000 (neighborhood), 5000 (city area), 20000 (metro area)." ), maxFuzzyLevel: z.number().optional().describe("Maximum fuzzy matching level (1-4)"), minFuzzyLevel: z.number().optional().describe("Minimum fuzzy matching level (1-4)"), entityTypeSet: z.string().optional() .describe(`Filter results by geographic entity types. Valid values: PostalCodeArea, CountryTertiarySubdivision, CountrySecondarySubdivision, MunicipalitySubdivision, MunicipalitySecondarySubdivision, Country, CountrySubdivision, Neighbourhood, Municipality. Note: This parameter is for geographic entities only, not POIs. For POI filtering, use categorySet instead` ), ofs: z.number().optional().describe("Offset for pagination of results"), idxSet: z.string().optional().describe("Filter results by index set"), relatedPois: z.string().optional().describe("Include related points of interest"), ext: z.string().optional().describe("Extended parameters for the search"), };
- src/tools/searchTools.ts:54-63 (registration)Registration of 'tomtom-fuzzy-search' tool on MCP server with title, description, input schema, and handler.// Fuzzy search tool server.registerTool( "tomtom-fuzzy-search", { title: "TomTom Fuzzy Search", description: "Typo-tolerant search for addresses, points of interest, and geographies", inputSchema: schemas.tomtomFuzzySearchSchema, }, createFuzzySearchHandler() );
- src/tools/searchOrbisTools.ts:54-63 (registration)Alternative Orbis registration of 'tomtom-fuzzy-search' tool using Orbis-specific handler and schema.// Fuzzy search tool server.registerTool( "tomtom-fuzzy-search", { title: "TomTom Fuzzy Search", description: "Typo-tolerant search for addresses, points of interest, and geographies", inputSchema: schemas.tomtomFuzzySearchSchema, }, createFuzzySearchHandler() );