API Reference

Route Enhancement API Reference

On this page

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`.
`densify`	query	integer	No	Insert interpolated vertices into the returned `geometry`, so that no segment is longer than `densifyGap`. Original vertices are kept. Elevations of the new vertices are interpolated if the input line has elevations for all vertices, otherwise they are taken from the terrain service. Only applies together with `elevation`. `1` — enabled (default when `elevation` is set) `0` — disabled, `geometry` keeps the input vertices Default: `1`. One of: `0`, `1`.
`densifyGap`	query	number	No	Maximum distance between vertices in meters when `densify` is enabled. Minimum `50`. Default: `100`.
`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.