Calculate Route

The calculate_route MCP tool calculates a route between two or more geographic waypoints for a supported travel mode.

Use this tool when you need route distance, travel time, geometry, or turn-by-turn instructions. Waypoints are processed in their array order unless optimize_stops is enabled.

Tool name

calculate_route

Request URL

https://api.geoapify.com/v1/mcp?apiKey=YOUR_API_KEY

Input parameters

Name	Type	Required	Description
`waypoints`	array of objects	Yes	Ordered route points with `lat` and `lon`. Provide at least an origin and destination.
`mode`	string	No	Travel or vehicle mode. Default: `drive`. See supported modes below.
`waypoint_mode`	string	No	Treatment of intermediate points: `stopover`, `through_stop`, or `pass_through`. Default: `stopover`.
`type`	string	No	Route preference: `balanced`, `short`, or `less_maneuvers`. Default: `balanced`.
`avoid`	array of strings	No	Up to three unique features to avoid: `tolls`, `ferries`, and `highways`.
`geometry_scope`	string	No	Geometry detail: `none`, `route`, `legs`, or `steps`. Default: `route`.
`geometry_format`	string	No	Geometry format: `geojson` or `polyline`. Default: `geojson`.
`include_instructions`	boolean	No	Include detailed turn-by-turn steps. Default: `false`.
`optimize_stops`	boolean	No	Optimize intermediate-stop order while preserving the first and last waypoint. Default: `false`.
`units`	string	No	`metric` or `imperial`. Default: `metric`.
`lang`	string	No	Language for turn-by-turn instructions. Default: `en`.
`traffic`	string	No	Traffic model for motorized routing: `free_flow` or `approximated`. Default: `free_flow`.

Each waypoint must contain a latitude from -90 to 90 and a longitude from -180 to 180. The input schema does not allow additional properties.

Supported modes are drive, light_truck, medium_truck, truck, heavy_truck, truck_dangerous_goods, long_truck, bus, scooter, motorcycle, bicycle, mountain_bike, road_bike, walk, hike, transit, and approximated_transit.

Example request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "calculate_route",
    "arguments": {
      "waypoints": [
        { "lat": 52.52, "lon": 13.405 },
        { "lat": 52.51, "lon": 13.39 }
      ],
      "mode": "drive",
      "geometry_scope": "none",
      "geometry_format": "geojson",
      "include_instructions": false
    }
  }
}

Response

The tool returns route units, waypoints, and legs. Depending on the requested options, the result can also include total distance and time, route or leg geometry, and instruction steps.

Example response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ ... }"
      }
    ],
    "structuredContent": {
      "distance": 2250,
      "units": "metric",
      "distance_units": "meters",
      "time": 222.763,
      "time_units": "seconds",
      "waypoints": [
        { "lat": 52.52, "lon": 13.405 },
        { "lat": 52.51, "lon": 13.39 }
      ],
      "legs": [
        {
          "distance": 2250,
          "time": 222.763
        }
      ]
    },
    "isError": false
  }
}

Related tools

Calculate Route Matrix - calculate travel times and distances for multiple source-target pairs.
Geocode Address - convert addresses into route waypoint coordinates.

Related API

For direct HTTP API integration, see Routing API.