Route Enhancement API

Use the Route Enhancement API to get the GeoJSON geometry of a GPX or KML file. You can extend it with elevation, surface, travel time estimates, or turn-by-turn instructions by adding extra parameters.

Base URL

https://enhance.maptoolkit.net/route

Use a POST request when the geometry is large, otherwise a GET request.

Authentication

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

Parameters

Route Data

Parameter	Type	Required	Description
`gpx`	URL	Yes (or `kml`/`geometry`)	URL to a GPX file.
`kml`	URL	Yes (or `gpx`/`geometry`)	URL to a KML file.
`geometry`	GeoJSON string	Yes (or `gpx`/`kml`)	A GeoJSON `LineString` or `MultiLineString`.

Data to add

Parameter	Type	Required	Description
`elevation`	`0` or `1`	No	Include an elevation profile in the response. Default: `0`.
`surface`	`0` or `1`	No	Include surface and road type data. Default: `0`.
`timings`	`0` or `1`	No	Include travel time estimates. Default: `0`.
`mapmatch`	`0` or `1`	No	Include turn-by-turn directions matched to the road network. Default: `0`.

Configuration Parameters

Parameter	Type	Required	Description
`routeType`	string	No	Vehicle type: `car`, `bike`, or `foot`.
`language`	string	No	Language for turn instructions, as a 2-letter code (e.g., `en`).
`cache`	`0` or `1`	No	Use cached results if available. Default: `1`.
`callback`	string	No	Wrap the response in a JSONP callback.

Response

GeoJSON from input route

GET https://enhance.maptoolkit.net/route?kml=https://maptoolkit.net/export/ts_demo_tours/_1603292819.kml&api_key=YOUR_API_KEY

Response:

{
  "geometry": {
    "type": "MultiLineString",
    "coordinates": [
      [
        [15.460422, 47.349047, 1181],
        [15.460593, 47.349027, 1179],
        ...
      ]
    ]
  }
}

Coordinates are [longitude, latitude, elevation_in_meters].

Add Elevation Data

GET https://enhance.maptoolkit.net/route?geometry={"type":"LineString","coordinates":[[10,50],[10.1,50.1]]}&elevation=1&api_key=YOUR_API_KEY

Response:

{
  "geometry": { "type": "MultiLineString", "coordinates": [[...]] },
  "elevation": [{
    "samples": [289, 292, 302, 305, 299],
    "distance": 13230.5,
    "ascent": 220,
    "descent": 160,
    "yrange": [200, 600],
    "labels": {
      "x": [[0, 0], [0.23, 3], [0.45, 6]],
      "y": [[0.25, 300], [0.5, 400], [0.75, 500]]
    }
  }]
}

Elevation samples are taken approximately every 100 meters. yrange gives the min/max values for the y-axis. Label values are relative positions (0–1) paired with the label value.

Add Surface Data

GET https://enhance.maptoolkit.net/route?kml=https://example.com/route.kml&surface=1&api_key=YOUR_API_KEY

Response:

{
  "geometry": { "type": "MultiLineString", "coordinates": [[...]] },
  "surface": [[
    { "from": 0.053, "to": 0.088, "highway": "road", "surface": "asphalt" },
    { "from": 0.088, "to": 0.106, "highway": "road", "surface": "paved" }
  ]]
}

from and to are relative positions along the route (0 = start, 1 = end).

Highway types:

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

Surface types:

asphalt, paved, unpaved, natural, alpine, other

Add Travel Time Estimates

GET https://enhance.maptoolkit.net/route?geometry={"type":"LineString","coordinates":[[10,50],[10.1,50.1]]}&timings=1&api_key=YOUR_API_KEY

Response:

{
  "geometry": { "type": "MultiLineString", "coordinates": [[...]] },
  "timings": [{
    "walking": 300,
    "cycling": 100,
    "cycling_offroad": 110,
    "cycling_racing": 50
  }]
}

Times are in seconds, calculated from route distance and elevation.

Add Turn-by-Turn Directions

Map matching generates turn-by-turn directions matched to the road network.

GET https://enhance.maptoolkit.net/route?kml=https://example.com/route.kml&mapmatch=1&language=en&api_key=YOUR_API_KEY

Response:

{
  "geometry": { "type": "MultiLineString", "coordinates": [[...]] },
  "mapmatch": [[{
    "instructions": [{
      "distance": 336.799,
      "name": "Kaufbeurer Straße",
      "text": "Turn right onto Kaufbeurer Straße",
      "sign": 2,
      "time": 67357,
      "coordinate": [47.83471, 10.82657],
      "tags": { "surface": "asphalt", "highway": "road" }
    }],
    "geometry": {
      "type": "LineString",
      "coordinates": [[10.82623, 47.83423], ...]
    }
  }]]
}