API Reference

Map Matching API Reference

Try the API in your browser

Base URL

https://routing.maptoolkit.net

Endpoints

`GET /match`

Match a track to the road network

Returns the recorded track snapped to the ways it was most likely recorded on.

Use GET for short tracks only. A recording of any length will not fit in a query string; use POST for those.

Parameter	In	Type	Required	Description
`point`	query	array	No	A recorded coordinate in `lat,lng` format, latitude first. Repeat the parameter once per point, in recorded order. Note the order: this is the opposite of the `[lng, lat]` used by GeoJSON, MapLibre and the map libraries. Passing map coordinates through without swapping them is the most common cause of a match that returns nothing useful. Required unless `gpx` is given.
`gpx`	query	string	No	URL of a GPX file to fetch and match. The service fetches it, not the browser, so a URL behind a login, on localhost or on a private network will fail. Required unless `point` is given.
`routeType`	query	string	No	Network to match against. Defaults to `foot`, not `car`. A car trace matched on the walking network snaps to footpaths no car took, so set this explicitly for anything that is not a walk. Accepted values: `car` - road network `bike` - cycling network `foot` - walking network (default) `hike` - hiking network `roads` - road cycling Default: `foot`. One of: `car`, `bike`, `foot`, `hike`, `roads`.
`language`	query	string	No	Language for the returned instructions as an ISO 639-1 code. Default: en.
`points_encoded`	query	string	No	Set to `false` or `0` to return the matched geometry as a GeoJSON LineString instead of an encoded polyline. Default: true. One of: `true`, `false`, `0`, `1`.

Status	Description
`200`	The matched track. The schema is identical to the Routing API response, so a client that already renders a route needs no changes to render a match. The geometry is at `paths[0].points`, encoded as a polyline unless `points_encoded=false`. `paths[0].distance` is the length of the matched line in metres, which will differ from the length of the recording: a track that wandered is longer than the ways it was recorded on, and one that cut corners is shorter.
`400`	Plain-text body, not JSON. One of: `No map-matching possible for your track.` The track was read but holds no usable points, or none of it could be matched to the network. `Request failed with status code 404` The URL given in `gpx` could not be fetched. Neither `point` nor `gpx` was supplied. The track is longer than the configured maximum length.
`403`	Plain-text body, not JSON. One of: `Access denied!` No API key was supplied, or it was sent in the POST body rather than the query string. `Api-key not found!` The key is not recognized. `Api-key not authorized!` The key is valid but has no access to this service.
`500`	Internal server error.

`POST /match`

Match a track to the road network (POST)

Identical to the GET form, with the track sent as application/x-www-form-urlencoded fields rather than query parameters. This is the form to use for a real recording, which will typically hold hundreds or thousands of points.

The api_key stays in the query string even here. In the body it is ignored.

Request body. The same fields as the GET parameters, form-encoded. Repeat point once per coordinate, or send a single gpx field holding a publicly reachable URL.

Status	Description
`200`	The matched track. The schema is identical to the Routing API response, so a client that already renders a route needs no changes to render a match. The geometry is at `paths[0].points`, encoded as a polyline unless `points_encoded=false`. `paths[0].distance` is the length of the matched line in metres, which will differ from the length of the recording: a track that wandered is longer than the ways it was recorded on, and one that cut corners is shorter.
`400`	Plain-text body, not JSON. One of: `No map-matching possible for your track.` The track was read but holds no usable points, or none of it could be matched to the network. `Request failed with status code 404` The URL given in `gpx` could not be fetched. Neither `point` nor `gpx` was supplied. The track is longer than the configured maximum length.
`403`	Plain-text body, not JSON. One of: `Access denied!` No API key was supplied, or it was sent in the POST body rather than the query string. `Api-key not found!` The key is not recognized. `Api-key not authorized!` The key is valid but has no access to this service.
`500`	Internal server error.

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.