Routing API

The Routing API calculates routes between two or more points. It supports car, bike, foot, and public transit, and returns turn-by-turn directions in JSON, GPX, or KML format.

Base URL

https://routing.maptoolkit.net/route

Authentication

Add your API key as ?api_key=YOUR_API_KEY to every request. See Authentication for details.

Parameters

Parameter	Type	Required	Description
`point`	`lat,lng`	Yes (min. 2)	A waypoint. Add this parameter multiple times to define the route. Order matters.
`routeType`	string	Yes	Vehicle type: `car`, `bike`, `foot`, or `transit`. Transit is currently available only in NRW, Germany.
`language`	string	No	Language for turn instructions, as an ISO 639-1 code (e.g., `en`, `de`).
`weighting`	string	No	Bike only. Route optimization: `networks` (default), `shortest`, or `fastest`.
`voice_instructions`	`0` or `1`	No	Adds voice instruction text to each turn. Default: `0`.
`finish_instruction`	`0` or `1`	No	Adds a finish instruction at the end of the route. Default: `0`.
`format`	string	No	Response format: `json` (default), `gpx`, or `kml`.
`departure`	date string	No	Departure time for transit routing.
`callback`	string	No	Wraps the response in a JSONP callback function.

Response

GET https://routing.maptoolkit.net/route?point=48.202596,16.369801&point=48.208373,16.370401&routeType=car&language=en&api_key=YOUR_API_KEY

This is a response to the HTTP GET request shown above:

{
  "info": {
    "copyrights": [
      "GraphHopper",
      "OpenStreetMap contributors"
    ],
    "took": 1,
    "road_data_timestamp": "2025-11-17T01:00:01Z"
  },
  "paths": [
    {
      "distance": 769.952,
      "weight": 168.289829,
      "time": 98995,
      "points_encoded": true,
      "bbox": [
        16.36885,
        48.202589,
        16.37053,
        48.20802
      ],
      "points": "eqeeHmf|bByD_BMCIVg@pDO`@Oj@INQ?a@OKMGIIMwAkAOC{@u@UYi@}@QU[SWIIASAG@GBIJQl@IH]nAIZy@m@uAw@k@YgBu@",
      "instructions": [
        {
          "distance": 117.483,
          "sign": 0,
          "interval": [
            0,
            2
          ],
          "text": "Continue onto Kärntner Straße",
          "time": 15105,
          "name": "Kärntner Straße",
          "distance_feet": 385,
          "distance_miles": 0.073000529193,
          "coordinate": [
            48.202589,
            16.369828
          ],
          "pushbike": false,
          "tags": {
            "highway": "street",
            "surface": "asphalt"
          },
          "speed": 27.999920556107252,
          "annotations": []
        },
        ...
      ],
      "ascend": 15.5657958984375,
      "descend": 6.759765625,
      "snapped_waypoints": "mf|bBeqeeHkC}`@",
      "ascend_feet": 51,
      "descend_feet": 22,
      "distance_feet": 2526,
      "distance_miles": 0.47842584419199996
    }
  ]
}

Response Fields

Field	Description
`paths[0].distance`	Total route distance in meters
`paths[0].time`	Total route time in milliseconds
`paths[0].points`	Encoded polyline of the full route
`paths[0].bbox`	Bounding box: `[minLon, minLat, maxLon, maxLat]`
`paths[0].instructions[].text`	Turn instruction text
`paths[0].instructions[].distance`	Distance for this step in meters
`paths[0].instructions[].time`	Duration for this step in milliseconds
`paths[0].instructions[].sign`	Turn direction code (see table below)
`paths[0].tags.highway`	Road type for this step
`paths[0].tags.surface`	Surface type for this step

Turn direction codes (`sign`)

Value	Meaning
`-3`	Sharp left
`-2`	Left
`-1`	Slight left
`0`	Continue straight
`1`	Slight right
`2`	Right
`3`	Sharp right
`4`	Finish
`5`	Via point reached
`6`	Roundabout

Highway types

motorway, primary, road, street, pedestrian, cycleway, path, hiking, mountain_hiking, other

Surface types

asphalt, paved, unpaved, natural, alpine, other

Examples

Working examples for this API, each with copyable source:

Maptoolkit Maps JS

Calculate a car route and draw it on a Maptoolkit map with turn-by-turn markers.

MapLibre GL JS

Calculate a car route and draw it on a MapLibre GL map with turn-by-turn markers.

Leaflet

Calculate a car route and draw it on a Leaflet map with turn-by-turn markers.

Build a Route Planner

Drag A or B to reroute, and hover a step to see it on the map.

Snap a GPS Track

Clean a recorded GPX trace with the Map Matching API and draw the raw and matched lines together.

Route Planner

Drag A or B to reroute, and hover a step to see it on the map.

Route Planner

Drag A or B to reroute, and hover a step to see it on the map.

Climb Statistics

Calculate total ascent, descent and the steepest section of a route from one Elevation API request.

Route by Surface Type

Colour a cycling route by what it runs on, using road surface data from the Route Enhancement API.

Route with Elevation Profile

Request a hiking route from the Routing API and chart its climb with the Maptoolkit elevation profile widget.

Errors

Errors return the HTTP status code with a plain-text message in the body.

Status	Meaning
`403`	The API key is missing (`Access denied!`) or not recognized (`Api-key not found!`). See First Steps.
`400`	The request is malformed, or the routing engine rejected it.

Common `400` messages

Message	Cause
`There is exactly on start and one endpoint allowed!`	Transit routing requires exactly two waypoints.
`Cannot parse departure time!`	`departure` is not a valid date string.
`Cannot handle request: {message}`	The transit routing engine returned an error.
`cannot parse custom_model: {message}`	`custom_model` is not valid JSON.

Errors from the upstream routing engine are forwarded as-is, so you may see messages that are not in this table.

Rate limits

Limits are monthly request quotas tied to your plan rather than a per-second rate: the service returns no RateLimit-* or Retry-After headers. Current allowances are on the pricing page.

The free Basic plan has a hard limit, so requests are refused once it is reached. On Pro and Ultra, requests past the allowance are billed rather than refused. Enterprise plans use a flexible limit.

Calls to this API count toward your plan’s API request allowance, which is the smaller of the two allowances.

Pricing

Self-service plans (Basic, Pro, and Ultra) are billed through RapidAPI; see RapidAPI for how to subscribe and authenticate. Plan limits and prices are listed on the Maptoolkit pricing page. Enterprise customers call the native hosts directly with a Maptoolkit API key.

Routing API

Base URL

Authentication

Parameters

Response

Response Fields

Turn direction codes (sign)

Highway types

Surface types

Examples

Errors

Common 400 messages

Rate limits

Pricing

Turn direction codes (`sign`)

Common `400` messages