API Reference

Routing API Reference

Base URL

https://routing.maptoolkit.net

Endpoints

`GET /match`

Snap a GPS track to the road network

Map-matches a sequence of coordinates or a GPX track to the nearest roads and returns a route in the same format as /route.

Parameter	In	Type	Required	Description
`point`	query	array	No	Track point in `lat,lng` format. Repeat to define the track. Required if `gpx` is not provided.
`gpx`	query	string	No	URL of a GPX file to use as the track input. Required if `point` is not provided.
`callback`	query	string	No	Wraps the response in a JSONP callback function with this name.
`format`	query	string	No	Response format. Default: json. One of: `json`, `gpx`, `kml`.
`routeType`	query	string	Yes	Travel mode. Accepted values: `car` — fastest road route `bike` — cycling route `foot` — walking route `hike` — hiking route `roads` — road cycling `transit` — public transit (available in NRW, Germany only; requires exactly 2 waypoints) One of: `car`, `bike`, `foot`, `hike`, `roads`, `transit`.

Status Description

Status	Description
`200`	Computed route. Content type depends on the `format` parameter: `format=json` (default): JSON route object `format=gpx`: GPX file download `format=kml`: KML file download
`400`	Bad request. Transit errors `There is exactly on start and one endpoint allowed!` — transit routing requires exactly 2 waypoints. `Cannot parse departure time!` — `departure` value is not a valid date string. `Cannot handle request: {message}` — transit routing engine returned an error. Routing errors `cannot parse custom_model: {message}` — `custom_model` is not valid JSON. General errors Upstream routing engine error message forwarded as-is.

200

Computed route. Content type depends on the format parameter:

format=json (default): JSON route object
format=gpx: GPX file download
format=kml: KML file download

400

Bad request.

Transit errors

There is exactly on start and one endpoint allowed! — transit routing requires exactly 2 waypoints.
Cannot parse departure time! — departure value is not a valid date string.
Cannot handle request: {message} — transit routing engine returned an error.

Routing errors

cannot parse custom_model: {message} — custom_model is not valid JSON.

General errors

Upstream routing engine error message forwarded as-is.

`GET /nearest`

Snap a coordinate to the nearest road

Returns the nearest point on the road network to the given coordinate.

Parameter	In	Type	Required	Description
`point`	query	string	Yes	Coordinate to snap in `lat,lng` format.
`callback`	query	string	No	Wraps the response in a JSONP callback function with this name.

Status Description

200 Nearest road point.

Status	Description
`200`	Nearest road point.
`400`	Bad request. Transit errors `There is exactly on start and one endpoint allowed!` — transit routing requires exactly 2 waypoints. `Cannot parse departure time!` — `departure` value is not a valid date string. `Cannot handle request: {message}` — transit routing engine returned an error. Routing errors `cannot parse custom_model: {message}` — `custom_model` is not valid JSON. General errors Upstream routing engine error message forwarded as-is.

400

Bad request.

Transit errors

There is exactly on start and one endpoint allowed! — transit routing requires exactly 2 waypoints.
Cannot parse departure time! — departure value is not a valid date string.
Cannot handle request: {message} — transit routing engine returned an error.

Routing errors

cannot parse custom_model: {message} — custom_model is not valid JSON.

General errors

Upstream routing engine error message forwarded as-is.

`GET /route`

Calculate a route

Returns a route between two or more waypoints with turn-by-turn instructions. Supports car, bike, foot, hiking, and public transit profiles.

Parameter	In	Type	Required	Description
`point`	query	array	Yes	Waypoint in `lat,lng` format. Repeat at least twice to define start and end. Order matters.
`routeType`	query	string	Yes	Travel mode. Accepted values: `car` — fastest road route `bike` — cycling route `foot` — walking route `hike` — hiking route `roads` — road cycling `transit` — public transit (available in NRW, Germany only; requires exactly 2 waypoints) One of: `car`, `bike`, `foot`, `hike`, `roads`, `transit`.
`callback`	query	string	No	Wraps the response in a JSONP callback function with this name.
`custom_model`	query	string	No	JSON-encoded GraphHopper custom model. Only used when `weighting=custom`.
`departure`	query	string	No	Departure time for transit routing as an ISO 8601 date-time string. Default: current time.
`details`	query	string	No	Set to `1` or `true` to include raw road segment details (road class, surface, track type) per instruction. Default: 0. One of: `0`, `1`, `true`, `false`.
`filename`	query	string	No	Sets the download filename (without extension) via `Content-Disposition`. Only used when `format=gpx` or `format=kml`.
`finish_instruction`	query	string	No	Set to `1` or `true` to include a finish instruction at the end of the turn-by-turn list. Default: 0. One of: `0`, `1`, `true`, `false`.
`format`	query	string	No	Response format. Default: json. One of: `json`, `gpx`, `kml`.
`language`	query	string	No	Language for turn instructions as an ISO 639-1 code. Default: en.
`points_encoded`	query	string	No	Set to `false` or `0` to return route geometry as a GeoJSON LineString instead of an encoded polyline. Default: true. One of: `true`, `false`, `0`, `1`.
`unit`	query	string	No	Unit system for voice instructions. Default: metric. One of: `metric`, `imperial`.
`vehicle`	query	string	No	Deprecated. Use `routeType` instead. One of: `car`, `bike`, `foot`, `hike`, `roads`, `transit`.
`voice_instructions`	query	string	No	Set to `1` or `true` to add voice instruction text to each turn. Default: 0. One of: `0`, `1`, `true`, `false`.
`weighting`	query	string	No	Route optimization strategy. Accepted values: `networks` (default) — recommended routes using precomputed road networks `fastest` — minimizes travel time `shortest` — minimizes distance `custom` — uses a custom GraphHopper model provided via `custom_model` One of: `networks`, `fastest`, `shortest`, `custom`.

Status Description

Status	Description
`200`	Computed route. Content type depends on the `format` parameter: `format=json` (default): JSON route object `format=gpx`: GPX file download `format=kml`: KML file download
`400`	Bad request. Transit errors `There is exactly on start and one endpoint allowed!` — transit routing requires exactly 2 waypoints. `Cannot parse departure time!` — `departure` value is not a valid date string. `Cannot handle request: {message}` — transit routing engine returned an error. Routing errors `cannot parse custom_model: {message}` — `custom_model` is not valid JSON. General errors Upstream routing engine error message forwarded as-is.

200

Computed route. Content type depends on the format parameter:

format=json (default): JSON route object
format=gpx: GPX file download
format=kml: KML file download

400

Bad request.

Transit errors

There is exactly on start and one endpoint allowed! — transit routing requires exactly 2 waypoints.
Cannot parse departure time! — departure value is not a valid date string.
Cannot handle request: {message} — transit routing engine returned an error.

Routing errors

cannot parse custom_model: {message} — custom_model is not valid JSON.

General errors

Upstream routing engine error message forwarded as-is.

`POST /route`

Calculate a route (POST)

Same as GET but accepts parameters in the request body. Useful when routing through many waypoints.

Status Description

Status	Description
`200`	Computed route. Content type depends on the `format` parameter: `format=json` (default): JSON route object `format=gpx`: GPX file download `format=kml`: KML file download
`400`	Bad request. Transit errors `There is exactly on start and one endpoint allowed!` — transit routing requires exactly 2 waypoints. `Cannot parse departure time!` — `departure` value is not a valid date string. `Cannot handle request: {message}` — transit routing engine returned an error. Routing errors `cannot parse custom_model: {message}` — `custom_model` is not valid JSON. General errors Upstream routing engine error message forwarded as-is.

200

Computed route. Content type depends on the format parameter:

format=json (default): JSON route object
format=gpx: GPX file download
format=kml: KML file download

400

Bad request.

Transit errors

There is exactly on start and one endpoint allowed! — transit routing requires exactly 2 waypoints.
Cannot parse departure time! — departure value is not a valid date string.
Cannot handle request: {message} — transit routing engine returned an error.

Routing errors

cannot parse custom_model: {message} — custom_model is not valid JSON.

General errors

Upstream routing engine error message forwarded as-is.

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.