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
`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,
      };
    }
  };
}

src/schemas/search/searchSchema.ts:182-228 (schema)

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()
);

TomTom MCP Server