tomtom-geocode
Convert addresses to precise geographic coordinates using detailed query inputs, language preferences, and country filters. Ideal for integrating accurate location data into applications and workflows.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| addressRanges | No | Include address ranges in the response | |
| btmRight | No | Bottom-right coordinates of bounding box (format: 'lat,lon'). Must be used with topLeft | |
| countrySet | No | Limit results to specific countries using ISO codes. Examples: 'US', 'FR,GB', 'CA,US' | |
| entityTypeSet | No | 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 | |
| extendedPostalCodesFor | No | Include extended postal codes for specific index types. Examples: 'PAD', 'PAD,Addr', 'POI' | |
| 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 | 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). | |
| query | Yes | Full address to convert to coordinates. Include as much detail as possible (street, city, country) for accurate results. Examples: '1600 Pennsylvania Ave, Washington DC', 'Eiffel Tower, Paris, France' | |
| radius | No | Search radius in meters when lat/lon provided | |
| 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 | |
| view | No | Geopolitical view for disputed territories. Options: 'Unified', 'AR', 'IL', 'IN', 'MA', 'PK', 'RU', 'TR', 'CN' |
Implementation Reference
- src/handlers/searchHandler.ts:27-46 (handler)Factory function creating the async handler for the 'tomtom-geocode' tool. It extracts the query, calls the geocodeAddress service with optional parameters, logs the process, and returns JSON-formatted results or error.
export function createGeocodeHandler() { return async (params: any) => { logger.info(`🏠 Geocoding: "${params.query}"`); try { const { query, ...options } = params; const result = await geocodeAddress( query, Object.keys(options).length > 0 ? options : undefined ); logger.info(`✅ Geocoding successful for: "${query}"`); return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] }; } catch (error: any) { logger.error(`❌ Geocoding failed: ${error.message}`); return { content: [{ type: "text" as const, text: JSON.stringify({ error: error.message }) }], isError: true, }; } }; } - Zod schema defining the input parameters for the 'tomtom-geocode' tool, including query and various search options.
export const tomtomGeocodeSearchSchema = { query: z .string() .describe( "Full address to convert to coordinates. Include as much detail as possible (street, city, country) for accurate results. Examples: '1600 Pennsylvania Ave, Washington DC', 'Eiffel Tower, Paris, France'" ), ...baseSearchParams, ...locationBiasParams, ...boundingBoxParams, 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` ), }; - src/tools/searchTools.ts:33-41 (registration)Registration of the 'tomtom-geocode' tool on the MCP server, specifying title, description, input schema, and handler function.
server.registerTool( "tomtom-geocode", { title: "TomTom Geocode", description: "Convert street addresses to coordinates (does not support points of interest)", inputSchema: schemas.tomtomGeocodeSearchSchema, }, createGeocodeHandler() );