tomtom-nearby
Search for points of interest near specific coordinates with customizable filters like category, brand, language, and radius using TomTom MCP Server's geolocation services.
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. | |
| categorySet | No | POI category filter. Common: '7315' (restaurants), '7309' (gas), '9663' (EV charging), '7311' (hotels), '9376' (parking). | |
| chargingAvailability | No | Include charging availability information for EV stations | |
| connectorSet | No | EV connector types: 'IEC62196Type2CableAttached', 'Chademo', 'TeslaConnector' | |
| 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' | |
| fuelAvailability | No | Include fuel availability information for gas stations | |
| fuelSet | No | Fuel types: 'Petrol', 'Diesel', 'LPG', 'Hydrogen', 'E85' | |
| geometries | No | Include geometries information in the response | |
| language | No | Preferred language for results using IETF language tags. Examples: 'en-US', 'fr-FR', 'de-DE', 'es-ES' | |
| lat | Yes | Center latitude for nearby search. Use precise coordinates from geocoding. | |
| limit | No | Maximum number of results to return (1-100). Default: 5 | |
| lon | Yes | Center longitude for nearby search. Use precise coordinates from geocoding. | |
| 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 | |
| parkingAvailability | No | Include parking availability information | |
| radius | No | Search radius in meters. Default: 1000. Recommended: 500 (walking), 1000 (local), 5000 (driving), 20000 (wide 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 | |
| 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:104-123 (handler)Factory function returning the MCP tool handler for 'tomtom-nearby'. Extracts lat/lon/options, calls searchNearby service, logs activity, and returns JSON-formatted results or error.export function createNearbySearchHandler() { return async (params: any) => { const { lat, lon, ...options } = params; const category = options.categorySet; logger.info( `🔍 Nearby search: (${lat}, ${lon}), category: ${category || "any"}, radius: ${options.radius || 1000}m` ); try { const result = await searchNearby(lat, lon, options); logger.info(`✅ Nearby search completed`); return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] }; } catch (error: any) { logger.error(`❌ Nearby search failed: ${error.message}`); return { content: [{ type: "text" as const, text: JSON.stringify({ error: error.message }) }], isError: true, }; } }; }
- Core service function implementing the nearby search logic by constructing API parameters and calling TomTom's /nearbySearch endpoint.export async function searchNearby( lat: number, lon: number, optionsOrCategory?: string | ExtendedSearchOptions, radiusParam?: number ): Promise<SearchResult> { // Handle backward compatibility let options: ExtendedSearchOptions; if (typeof optionsOrCategory === "string" || optionsOrCategory === undefined) { options = { categorySet: optionsOrCategory, radius: radiusParam || 1000, }; } else { options = optionsOrCategory; } const params = buildSearchParams(options, { radius: 1000, limit: 20, language: "en-US", }); // Add lat/lon directly since they're required for nearby search params.lat = lat; params.lon = lon; const categoryInfo = options.categorySet ? `, category: ${options.categorySet}` : ", category: any"; const radiusInfo = options.radius || 1000; return makeApiCall( `/search/${API_VERSION.SEARCH}/nearbySearch/.json`, params, `Searching nearby: (${lat}, ${lon})${categoryInfo}, radius: ${radiusInfo}m` ); }
- Zod-based input schema for the tomtom-nearby tool, defining required lat/lon and optional parameters like radius, categorySet, and various filters.export const tomtomNearbySearchSchema = { lat: z .number() .describe("Center latitude for nearby search. Use precise coordinates from geocoding."), lon: z .number() .describe("Center longitude for nearby search. Use precise coordinates from geocoding."), ...baseSearchParams, ...poiFilterParams, radius: z .number() .optional() .describe( "Search radius in meters. Default: 1000. Recommended: 500 (walking), 1000 (local), 5000 (driving), 20000 (wide area)." ), categorySet: z .string() .optional() .describe( `Filter POI per category using category IDs. Examples: '7315' (Restaurant), '9361' (Shop), '7311' (Gas Station), '7321' (Hospital), '7397' (ATM), '7327' (Department Store), '7314' (Hotel/Motel), '9361009' (Convenience Store), '7324' (Post Office), '7383' (Airport), '7380' (Railroad Station), '9942' (Public Transportation Stop), '7313' (Parking Garage), '7369' (Open Parking Area), '7342' (Movie Theater), '9362' (Park & Recreation Area), '7310' (Repair Shop), '9376' (Café/Pub), '9379' (Nightlife), '7318' (Theater), '7317' (Museum), '7312' (Rent-a-Car Facility), '7372' (School), '7322' (Police Station), '7326' (Pharmacy), '9352' (Company), '7376' (Tourist Attraction), '7332005' (Supermarkets & Hypermarkets), '7315015' (Fast Food)` ), 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` ), chargingAvailability: z .boolean() .optional() .describe("Include charging availability information for EV stations"), parkingAvailability: z.boolean().optional().describe("Include parking availability information"), fuelAvailability: z .boolean() .optional() .describe("Include fuel availability information for gas stations"), minFuzzyLevel: z.number().optional().describe("Minimum fuzzy matching level (1-4)"), maxFuzzyLevel: z.number().optional().describe("Maximum fuzzy matching level (1-4)"), roadUse: z.boolean().optional().describe("Include road usage information"), ofs: z.number().optional().describe("Offset for pagination of results"), relatedPois: z.string().optional().describe("Include related points of interest"), ext: z.string().optional().describe("Extended parameters for the search"), };
- src/tools/searchTools.ts:77-86 (registration)Registers the 'tomtom-nearby' tool with the MCP server using the nearby search handler and schema.server.registerTool( "tomtom-nearby", { title: "TomTom Nearby Search", description: "Discover services within a radius", inputSchema: schemas.tomtomNearbySearchSchema, }, createNearbySearchHandler() ); }