POST /v1/route calculates a route. POST /v1/shape finds the plan points of a route that follows
a line. GET /v1/region describes the routing package. Request and answer bodies are UTF-8 JSON.
- Writers: the route service; the native provider answers
routeandshapewith the same code (planner_router_callwith the callrouteorshape). The answer encoder isplanner/router/src/answer.rs. - Readers: the web planner (
builder/web/src/lib/planner/routing.ts,route-answer.ts), the companion app (OBCPlanner/PlannerService.swift,RouteAnswer.swift). - Test vectors:
vectors/route-answer.json: one route before and after encoding. The encoder test and each decoder test read it. - Related: route package, route catalog.
| Field | Value |
|---|---|
points |
2 to 64 ordered [longitude, latitude] pairs in degrees |
profile |
A profile ID from GET /v1/region |
pace |
Optional: cycling_kmh (1 to 80, default 19), walking_kmh (0.5 to 15, default 4.5) and personal_multiplier (0.25 to 4, default 1) |
turnarounds |
Optional interior point indices where a reversal is deliberate |
start_position |
Optional leg position from an earlier answer. It pins the first point to that road position |
end_position |
Optional leg position from an earlier answer. It pins the last point to that road position |
The service rejects unknown fields.
The answer is {"routes": [...]}. It holds one route. The route has these fields:
| Field | Value |
|---|---|
id |
64-character lowercase hex route identity |
package |
Routing package identity |
profile |
Profile ID of this route |
coordinates_udeg |
Integer microdegrees: longitude and latitude of each point, flat |
elevation_dm |
Integer decimetres, or null where the height is unknown |
elapsed_s |
Integer moving seconds |
edges |
One run channel for each fact of an edge, by name |
legs |
{"from_index", "to_index", "start", "end", "totals"} for each pair of request points |
snap_truncated |
true when the service dropped road candidates for a request point |
totals |
distance_m, ascent_m, seconds, surface_m, unknown_elevation_m and pushing_m, all integers |
coordinates_udeg holds two integers for each point: longitude, then latitude. The first pair is
absolute. Each pair after it is the difference from the previous point. Add the pairs in sequence
and divide by 1,000,000 to get degrees.
elevation_dm and elapsed_s hold one integer for each point. Each value is the difference from
the previous value. The value before the first point is zero. Add the values in sequence. Divide the
heights by 10 to get metres. A null height adds nothing: the next height is a difference from the
last known height. The first elapsed value is zero.
The encoder rounds the absolute value of each point and then calculates the difference, so rounding errors do not add up.
An edge joins point i and point i + 1. A route with n points has n - 1 edges. edges maps
each channel name to a list of runs [value, edge count]. Each run gives one value and the number
of consecutive edges with that value. The run lengths of a channel add up to n - 1. A missing
channel is null on every edge. A client accepts a channel that it does not know.
| Channel | Value of an edge |
|---|---|
surfaces |
Unknown, Paved, Compacted, Gravel, Dirt or Rough |
pushing |
true where the rider must push the bicycle |
closures |
null, or a list of possible closures, each {"kind", "condition"} |
sac_scale |
The OSM sac_scale as an integer from 0 (strolling) through 1 (hiking, T1) to 6 (difficult_alpine_hiking, T6), or null when the way has none |
The router blocks a mode only for the access value no; dismount blocks riding only. It uses an
edge that is possibly closed for the mode that the route uses on it, and reports it. A way or a
node whose access value is destination, alone, in a list with other groups or in a conditional
clause, carries no closure. A closure on a node, such as a gate,
belongs to the edges of the road that arrives at the node. A closure applies
only to the direction of travel that its tag names. A closure from an access value makes the road
cost three times its length, and a node cost as much as 300 m of good road. A seasonal or
conditional closure adds no cost:
kind |
Source | condition |
|---|---|---|
permit |
Access value permit |
permit |
private |
Access value private |
private |
farm |
Access value agricultural or forestry |
The value |
sidepath |
Access value use_sidepath |
use_sidepath |
discouraged |
Access value discouraged |
discouraged |
limited |
Access value for another group: customers, delivery, residents, military, or a motor group such as psv |
The value |
seasonal |
A conditional restriction that names only months, days or seasons | The OSM condition, such as Nov-May |
conditional |
Any other conditional restriction | The OSM condition, such as wet |
unclear |
An access value or a barrier that the router does not know, or a reversible one-way | The value, barrier=VALUE, or oneway=reversible |
legs[k].from_index and legs[k].to_index are inclusive point indices. The first leg starts at
index 0. Each leg starts where the previous leg ends. The last leg ends at index n - 1.
surface_m gives metres for each surface, in the order above. seconds is moving time. Distances
and heights are metres.
start and end are opaque strings. Each names the snapped road position of a leg end: the road
and the direction of travel on it. Where a point is not a turnaround, the end of one leg equals
the start of the next leg. A client compares positions only for equality and sends them back
unchanged.
A pinned point keeps only the road candidate at that position. Thus a request for some legs of a
trip joins the legs before and after it in the same direction. The service ignores a position that
is not a candidate of the point, for example a position from a different package.
legs[k].totals has the fields of the route totals, for that leg only. The sum of the leg totals
is the route total. Only seconds can differ, by up to 0.5 s for each leg.
Coordinates are exact: the routing engine stores microdegrees. Heights are within 0.05 m of the engine value. Elapsed and total seconds are within 0.5 s.
The service compresses with brotli or gzip, as Accept-Encoding permits. It prefers brotli.
POST /v1/shape finds plan points for a line, for example a GPX track. A route request with these
points and the same profile follows the line.
| Field | Value |
|---|---|
line |
2 to 2,000 [longitude, latitude] pairs in degrees, at most 200 km long |
profile |
A profile ID from GET /v1/region |
The service rejects unknown fields. The body limit is 64 KiB for both requests. Simplify a track within 10 m and send 6 decimals before the request: then a 200 km track fits. The service also simplifies the line within 10 m.
The answer is {"points": [...], "turnarounds": [...]}:
| Field | Value |
|---|---|
points |
2 to 64 [longitude, latitude] pairs in degrees, in route order |
turnarounds |
Ascending indices in points where the line turns back |
Each point is on a road, where the route attaches it. The first point is the start of the line, and
the last point is the end of the line. Send turnarounds unchanged as the turnarounds of the
route request.
The route follows the line when its deviation is at most 2 % of the line length. The deviation is the length of the route farther than 30 m from the line, plus the length of the line farther than 30 m from the route. The line turns back at a point when, for 150 m before and after the point, it stays within 30 m of itself. A hairpin bend is not a turnaround.
One shape request uses one profile and at most 200 route calculations. Each has the limits of a route request. The deadline is 30 s.
GET /v1/region answers with these fields:
| Field | Value |
|---|---|
package |
Routing package identity |
region |
Region ID |
bounds |
[west, south, east, north] in degrees |
profiles |
The profile IDs that requests can use |
attribution |
Data credits |
warnings |
Strings that name known limits of the package data |
A profile ID is an activity, such as touring, or an activity, / and a variant. Each activity
has one variant: touring/less-climbing, road/less-climbing, gravel/less-climbing,
mtb/technical and hiking/alpine. Two variants are skill choices. mtb/technical permits every MTB grade;
mtb permits S2 at most. hiking/alpine permits each grade up to T6; hiking permits T2 at most. Cycling profiles
never use steps. The clients offer the presets of the profiles that the region serves.
An error answer is {"code", "message"}; a no_snap answer also has point, the index of the
point, from 0; a no_path answer also has leg, the index of the leg from 0, between point leg
and leg + 1. It never contains a substitute route.
The service attaches each point to the nearest road that the profile can use and that lies in a
large connected part of its road graph, within 250 m. When none is that near, it uses the nearest
such road within 1 km. no_snap means that no such road is within 1 km. no_path means that no
legal route joins two consecutive points; the service does not try other roads for them.
line_too_long means that a shape line has more than 2,000 points or is longer than 200 km.
line_not_reproducible means that the search found no plan of at most 64 points that follows the
line, within its 200 route calculations.
limit means that the request exceeds a fixed limit of the service. The same request fails again;
plan the route in shorter parts. busy means that no worker became free within 1 s, or that a
worker had no memory for the request at that moment. internal means that the service failed, not
the request or the data. For busy and internal, send the request again later.
Shape requests can use at most max(1, workers / 2) workers. With 1 worker, a route request waits
behind a shape request. A body larger than the limit is an
invalid_request. A call other than route and shape is not_found.
| Code | Status |
|---|---|
invalid_request |
400 |
not_found |
404 |
no_snap, no_path, missing_region |
422 |
line_too_long, line_not_reproducible, limit |
422 |
cancelled |
408 |
busy |
503 |
invalid_data, internal |
500 |