tomtom-reverse-geocode
Convert latitude and longitude coordinates into human-readable addresses using TomTom's geocoding capabilities. Specify language, country set, and additional details like mapcodes, geopolitical views, or extended postal codes for precise, customizable results.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| addressRanges | No | Include address ranges in the response | |
| allowFreeformNewLine | No | Allow newlines in freeform addresses | |
| countrySet | No | Limit results to specific countries using ISO codes. Examples: 'US', 'FR,GB', 'CA,US' | |
| entityTypeSet | No | Filter by entity types: 'Country', 'Municipality', etc. | |
| extendedPostalCodesFor | No | Include extended postal codes for specific index types. Examples: 'PAD', 'PAD,Addr', 'POI' | |
| geometries | No | Include geometries information in the response | |
| heading | No | Heading direction in degrees (0-360) for improved accuracy on roads | |
| language | No | Preferred language for results using IETF language tags. Examples: 'en-US', 'fr-FR', 'de-DE', 'es-ES' | |
| lat | Yes | Latitude coordinate (-90 to +90). Precision to 4+ decimal places recommended. | |
| limit | No | Maximum number of results to return (1-100). Default: 5 | |
| lon | Yes | Longitude coordinate (-180 to +180). Precision to 4+ decimal places recommended. | |
| 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). | |
| maxResults | No | Maximum results to return (alias for limit) | |
| ofs | No | Offset for pagination of results | |
| radius | No | Search radius in meters. Default: 100 | |
| returnAddressNames | No | Include address names in the response | |
| returnCommune | No | Include commune information in the results | |
| returnMatchType | No | Include information about the type of geocoding match achieved | |
| returnRoadAccessibility | No | Include road accessibility information | |
| returnRoadUse | No | Include road use types for street level results | |
| returnSpeedLimit | No | Include posted speed limit for street results | |
| roadUse | No | Types of road use to include in the results. Examples: 'Arterial', 'Ferry', 'Highway', etc. | |
| 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 | |
| view | No | Geopolitical view for disputed territories. Options: 'Unified', 'AR', 'IL', 'IN', 'MA', 'PK', 'RU', 'TR', 'CN' |
Implementation Reference
- src/handlers/searchHandler.ts:48-68 (handler)MCP tool handler factory for 'tomtom-reverse-geocode'. Extracts lat/lon/options, calls reverseGeocode service, logs progress, returns JSON result or error response.export function createReverseGeocodeHandler() { return async (params: any) => { const { lat, lon, ...options } = params; logger.info(`📍 Reverse geocoding: (${lat}, ${lon})`); try { const result = await reverseGeocode( lat, lon, Object.keys(options).length > 0 ? options : undefined ); logger.info(`✅ Reverse geocoding successful`); return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] }; } catch (error: any) { logger.error(`❌ Reverse geocoding failed: ${error.message}`); return { content: [{ type: "text" as const, text: JSON.stringify({ error: error.message }) }], isError: true, }; } }; }
- Zod input schema for tomtom-reverse-geocode tool, defining lat, lon, and various optional search parameters like radius, entity types, and formatting options.export const tomtomReverseGeocodeSearchSchema = { lat: z .number() .describe("Latitude coordinate (-90 to +90). Precision to 4+ decimal places recommended."), lon: z .number() .describe("Longitude coordinate (-180 to +180). Precision to 4+ decimal places recommended."), ...baseSearchParams, radius: z.number().optional().describe("Search radius in meters. Default: 100"), 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` ), returnMatchType: z .boolean() .optional() .describe("Include information about the type of geocoding match achieved"), returnSpeedLimit: z .boolean() .optional() .describe("Include posted speed limit for street results"), returnRoadUse: z.boolean().optional().describe("Include road use types for street level results"), roadUse: z .array(z.string()) .optional() .describe( "Types of road use to include in the results. Examples: 'Arterial', 'Ferry', 'Highway', etc." ), allowFreeformNewLine: z.boolean().optional().describe("Allow newlines in freeform addresses"), returnAddressNames: z.boolean().optional().describe("Include address names in the response"), heading: z .number() .optional() .describe("Heading direction in degrees (0-360) for improved accuracy on roads"), maxResults: z.number().optional().describe("Maximum results to return (alias for limit)"), returnRoadAccessibility: z .boolean() .optional() .describe("Include road accessibility information"), returnCommune: z.boolean().optional().describe("Include commune information in the results"), ofs: z.number().optional().describe("Offset for pagination of results"), };
- src/tools/searchTools.ts:44-52 (registration)MCP server registration of 'tomtom-reverse-geocode' tool with title, description, input schema, and handler factory.server.registerTool( "tomtom-reverse-geocode", { title: "TomTom Reverse Geocode", description: "Convert coordinates to addresses", inputSchema: schemas.tomtomReverseGeocodeSearchSchema, }, createReverseGeocodeHandler() );
- src/handlers/searchOrbisHandler.ts:48-68 (handler)Orbis variant of MCP tool handler factory for 'tomtom-reverse-geocode', identical logic but uses Orbis service.export function createReverseGeocodeHandler() { return async (params: any) => { const { lat, lon, ...options } = params; logger.info(`📍 Reverse geocoding: (${lat}, ${lon})`); try { const result = await reverseGeocode( lat, lon, Object.keys(options).length > 0 ? options : undefined ); logger.info(`✅ Reverse geocoding successful`); return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] }; } catch (error: any) { logger.error(`❌ Reverse geocoding failed: ${error.message}`); return { content: [{ type: "text" as const, text: JSON.stringify({ error: error.message }) }], isError: true, }; } }; }
- src/tools/searchOrbisTools.ts:44-52 (registration)Orbis variant MCP server registration of 'tomtom-reverse-geocode' tool using Orbis schema and handler.server.registerTool( "tomtom-reverse-geocode", { title: "TomTom Reverse Geocode", description: "Convert coordinates to addresses", inputSchema: schemas.tomtomReverseGeocodeSearchSchema, }, createReverseGeocodeHandler() );