API Reference

Route Enhancement API Reference

Base URL

https://enhance.maptoolkit.net

Endpoints

`GET /route`

Enhance a route (GET)

Accepts route data as query parameters. Use POST /route when the geometry payload is too large for a URL (e.g. large GPX strings).

Parameter	In	Type	Required	Description
`api_key`	query	string	No	API key for authentication. See Authentication.
`gpx`	query	string	No	GPX route data. Either a URL to a GPX file (`https://…`) or the raw GPX XML string. One of `gpx`, `kml`, or `geometry` is required.
`kml`	query	string	No	KML route data. Either a URL to a KML file (`https://…`) or the raw KML XML string. One of `gpx`, `kml`, or `geometry` is required.
`geometry`	query	string	No	Route geometry as a GeoJSON `LineString` or `MultiLineString` JSON string. One of `gpx`, `kml`, or `geometry` is required.
`elevation`	query		No	Include an elevation profile in the response. `0` — disabled (default) `1` — enabled with default options JSON object — enabled with custom options: `gap` (number) — sampling interval in meters. Default: `100`, or `distance / 1000` for routes longer than 100 km. `tolerance` (number) — Douglas-Peucker simplification tolerance in meters applied to the chart data. Default: `20`. `width` (integer) — chart width in pixels, used for x-axis label positions. Default: `500`. `height` (integer) — chart height in pixels, used for y-axis label positions. Default: `100`. `dy` (integer) — y-axis range span in meters. Default: `300`.
`surface`	query		No	Include surface and highway type data in the response. Uses map matching to snap route segments to the road network. `0` — disabled (default) `1` — enabled with default options JSON object — enabled with custom options: `mapMatchingThreshold` (number) — maximum relative distance deviation to accept a map match. A segment is classified as `other` if `\|1 - matchDistance/origDistance\| >= threshold`. Default: `0.05`.
`mapmatch`	query	integer	No	Include map-matched turn-by-turn instructions in the response. Snaps the route to the road network and returns navigation instructions per segment. `0` — disabled (default) `1` — enabled One of: `0`, `1`.
`timings`	query	integer	No	Include travel time estimates in the response. Times are calculated from route distance and elevation data. Automatically enables `elevation` if not already set. `0` — disabled (default) `1` — enabled One of: `0`, `1`.
`routeType`	query	string	No	Vehicle profile used for map matching and routing. 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. The cache key is derived from all route and enrichment parameters. Pass `0` to force a fresh computation. Default: `1`. One of: `0`, `1`.
`key`	query	string	No	Override the auto-generated cache key. Useful for pre-warming or sharing cached results. If omitted, the key is derived from the MD5 hash of all route parameters.
`callback`	query	string	No	Wrap the JSON response in a JSONP callback function with this name.

Status Description

200 Route enhancement result.

Status	Description
`200`	Route enhancement result.
`400`	Bad request. Possible error messages: `no valid geometry found, LineString & MultiLineString's are allowed` — `geometry` parameter is missing or has an unsupported GeoJSON type. `invalid geometry type` — GeoJSON type is parsed but not `LineString` or `MultiLineString`. `param '{name}' seems to be a JSON String, but it cannot be parsed: {message}` — A parameter value starts with `{` but is not valid JSON. `routing request failed: {message}` — Upstream routing service error (surface/mapmatch).

400

Bad request. Possible error messages:

no valid geometry found, LineString & MultiLineString's are allowed — geometry parameter is missing or has an unsupported GeoJSON type.
invalid geometry type — GeoJSON type is parsed but not LineString or MultiLineString.
param '{name}' seems to be a JSON String, but it cannot be parsed: {message} — A parameter value starts with { but is not valid JSON.
routing request failed: {message} — Upstream routing service error (surface/mapmatch).

`POST /route`

Enhance a route (POST)

Accepts route data as a JSON body. Preferred for large GPX/KML 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 Route enhancement result.

Status	Description
`200`	Route enhancement result.
`400`	Bad request. Possible error messages: `no valid geometry found, LineString & MultiLineString's are allowed` — `geometry` parameter is missing or has an unsupported GeoJSON type. `invalid geometry type` — GeoJSON type is parsed but not `LineString` or `MultiLineString`. `param '{name}' seems to be a JSON String, but it cannot be parsed: {message}` — A parameter value starts with `{` but is not valid JSON. `routing request failed: {message}` — Upstream routing service error (surface/mapmatch).

400

Bad request. Possible error messages:

no valid geometry found, LineString & MultiLineString's are allowed — geometry parameter is missing or has an unsupported GeoJSON type.
invalid geometry type — GeoJSON type is parsed but not LineString or MultiLineString.
param '{name}' seems to be a JSON String, but it cannot be parsed: {message} — A parameter value starts with { but is not valid JSON.
routing request failed: {message} — Upstream routing service error (surface/mapmatch).

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.