API Reference

Routing Enhancement API Reference

Base URL

https://enhance.maptoolkit.net

Endpoints

`GET /routing`

Route along a trail (GET)

Accepts routing parameters as query parameters.

Parameter	In	Type	Required	Description
`api_key`	query	string	No	API key for authentication. See Authentication.
`start`	query	string	Yes	Start coordinate in `lng,lat` format.
`end`	query	string	Yes	End coordinate in `lng,lat` format.
`gpx`	query	string	No	URL to the trail GPX file (forward direction). One of `gpx`, `kml`, or `geometry` is required.
`gpx_backward`	query	string	No	URL to the trail GPX file in the reverse direction. If omitted, the forward trail is also used for backward routing.
`kml`	query	string	No	URL to the trail KML file (forward direction). One of `gpx`, `kml`, or `geometry` is required.
`kml_backward`	query	string	No	URL to the trail KML file in the reverse direction. If omitted, the forward trail is also used for backward routing.
`geometry`	query	string	No	Forward-direction trail as a GeoJSON `LineString` JSON string. One of `gpx`, `kml`, or `geometry` is required.
`geometry_backward`	query	string	No	Reverse-direction trail as a GeoJSON `LineString` JSON string. If omitted, the forward geometry is also used for backward routing.
`mapmatch`	query	integer	No	Map matching is enabled by default. It snaps the trail to the road network before routing, which improves instruction quality. Set to `0` to disable and connect start/end to the trail geometrically instead. Default: `1`. One of: `0`, `1`.
`routeType`	query	string	No	Vehicle profile used for road-network routing between waypoints. Default: `bike`. One of: `bike`, `car`, `foot`.
`language`	query	string	No	Language for turn-by-turn instructions as an ISO 639-1 code. Default: `en`.
`cache`	query	integer	No	Use cached results when available. Pass `0` to force a fresh computation. Default: `1`. One of: `0`, `1`.
`callback`	query	string	No	Wrap the JSON response in a JSONP callback function with this name.

Status Description

200 Trail routing result.

Status	Description
`200`	Trail routing result.
`400`	Bad request. Possible error messages: `no start point defined` — `start` parameter missing. `no end point defined` — `end` parameter missing. `cannot load forward route` — Trail route fetch or processing failed. `cannot load backward route` — Backward trail route fetch or processing failed. `Only LineStrings are allowed for forward/backward route` — Trail geometry contains multiple segments (MultiLineString not supported here). `routing from point to route not possible` — Road-network routing from start/end to the trail failed. `start not routeable` — Start coordinate could not be connected to the trail. `routing request failed: {message}` — Upstream routing service error. `param '{name}' seems to be a JSON String, but it cannot be parsed: {message}` — A parameter value starts with `{` but is not valid JSON.

400

Bad request. Possible error messages:

no start point defined — start parameter missing.
no end point defined — end parameter missing.
cannot load forward route — Trail route fetch or processing failed.
cannot load backward route — Backward trail route fetch or processing failed.
Only LineStrings are allowed for forward/backward route — Trail geometry contains multiple segments (MultiLineString not supported here).
routing from point to route not possible — Road-network routing from start/end to the trail failed.
start not routeable — Start coordinate could not be connected to the trail.
routing request failed: {message} — Upstream routing service error.
param '{name}' seems to be a JSON String, but it cannot be parsed: {message} — A parameter value starts with { but is not valid JSON.

`POST /routing`

Route along a trail (POST)

Accepts routing parameters as a JSON body. Preferred for large trail payloads (up to 50 MB). api_key can be passed as a query parameter or in the body.

Parameter	In	Type	Required	Description
`api_key`	query	string	No	API key for authentication. See Authentication.

Status Description

200 Trail routing result.

Status	Description
`200`	Trail routing result.
`400`	Bad request. Possible error messages: `no start point defined` — `start` parameter missing. `no end point defined` — `end` parameter missing. `cannot load forward route` — Trail route fetch or processing failed. `cannot load backward route` — Backward trail route fetch or processing failed. `Only LineStrings are allowed for forward/backward route` — Trail geometry contains multiple segments (MultiLineString not supported here). `routing from point to route not possible` — Road-network routing from start/end to the trail failed. `start not routeable` — Start coordinate could not be connected to the trail. `routing request failed: {message}` — Upstream routing service error. `param '{name}' seems to be a JSON String, but it cannot be parsed: {message}` — A parameter value starts with `{` but is not valid JSON.

400

Bad request. Possible error messages:

no start point defined — start parameter missing.
no end point defined — end parameter missing.
cannot load forward route — Trail route fetch or processing failed.
cannot load backward route — Backward trail route fetch or processing failed.
Only LineStrings are allowed for forward/backward route — Trail geometry contains multiple segments (MultiLineString not supported here).
routing from point to route not possible — Road-network routing from start/end to the trail failed.
start not routeable — Start coordinate could not be connected to the trail.
routing request failed: {message} — Upstream routing service error.
param '{name}' seems to be a JSON String, but it cannot be parsed: {message} — A parameter value starts with { but is not valid JSON.

Try it

The console below sends live requests against the endpoints above. You can browse it without an API key; Execute needs one, because every endpoint requires the api_key query parameter and returns 403 without it. Use Authorize to add your key. See First Steps if you do not have one yet.