Directions
The Directions API computes routes on the full OSM road and path network, returning a GeoJSON LineString geometry with distance and duration.
Directions is a premium endpoint — each request counts as 4x.
Endpoint
Section titled “Endpoint”POST /api/v1/routeRequest body
Section titled “Request body”| Field | Type | Default | Description |
|---|---|---|---|
origin | GeoJSON Point | — | Required. Start point ([longitude, latitude]). |
destination | GeoJSON Point | — | Required. End point ([longitude, latitude]). |
mode | string | "auto" | Travel mode: auto, foot, bicycle, truck, motorcycle, motor_scooter or transit. Aliases work too: car and drive for auto, walk for foot, bike for bicycle, motorbike for motorcycle, scooter and moped for motor_scooter. Any other value is a 422 validation_error listing the modes. truck takes a truck vehicle object, see Truck Routing. bicycle takes an optional bicycle object and foot a pedestrian object, see Cycling and Walking Options. motorcycle takes an optional motorcycle object and motor_scooter a motor_scooter object, see Motorcycle and Scooter Routing. transit walks and rides buses, trains and ferries from GTFS timetables and takes its own options, see Transit Routing. |
waypoints | GeoJSON Point[] | — | Intermediate stops (max 25). Route visits them in order. Can’t be combined with alternatives. |
alternatives | int | 0 | Number of alternative routes (0–3). |
steps | boolean | false | Include turn-by-turn steps in properties.steps. See Turn-by-turn steps. |
lang | string | from Accept-Language, else "en" | Language for step instructions, as a BCP 47 tag ("fr", "pt-BR"). See Languages. An unsupported lang is a 422. |
units | string | from lang | km or mi for distances inside instructions. Defaults to mi when the lang region is US, GB, LR or MM, otherwise km. |
verbal | boolean | false | Add spoken variants to each step. Needs steps. Anything other than true or false is a 422. |
voice_instructions | boolean | false | Add timed voice announcements to each step. Needs steps. See Navigation. |
banner_instructions | boolean | false | Add banner content (road, ref, destinations, lanes) to each step. Needs steps. |
roundabout_exits | boolean | false | Give leaving a roundabout its own exit_roundabout (or exit_rotary) step. Needs steps. |
voice_units | string | units | metric or imperial for distances in voice announcements. |
waypoint_names | array or string | — | One name per point (origin, each waypoint, destination) for arrival instructions. null or "" keeps the default. A list, or a ;-separated string. The wrong count is a 422. |
annotations | boolean | false | Include per-edge metadata (speed, duration, surface). With steps, each leg also gets per-coordinate arrays. |
overview | string | "full" | Geometry detail: full, simplified, or false. Step geometries always use the full line. |
geometries | string | "geojson" | Encoding for the route and each step’s geometry: geojson, polyline, or polyline6. |
exclude | string | — | Comma-separated road types to avoid: toll, cash_only_tolls, ferry, unpaved, motorway, trunk, primary, secondary, tertiary. Unknown values are a 400. cash_only_tolls avoids roads through a toll booth that takes only cash. See cash-only tolls. |
avoid_datasets | string or array | — | Keep out of the polygons of these datasets: up to 10 slugs or IDs. See avoiding areas. |
datasets | string or array | — | Also drive, ride or walk the roads in these datasets: up to 20 slugs or IDs. See your own roads. |
depart_at | string | — | Departure time: ISO 8601 with Z or an offset (an instant) or without one (local time at the origin), or "now". Adjusts speeds by time of day and applies conditional limits. Any other value is a 422. See Traffic-Aware Routing. |
traffic_model | string | "best_guess" | best_guess, pessimistic or optimistic. Used with depart_at. Any other value is a 422. |
ev | object | — | Plan charging stops for an electric vehicle. See EV Routing. |
use_highways, use_tolls, use_ferries, use_living_streets, use_tracks, shortest, top_speed, fixed_speed, maneuver_penalty, service_penalty, gate_cost, toll_booth_cost, country_crossing_cost | — | Lean towards or away from road types, minimise distance, cap the speed or penalise turns. See Route Preferences. | |
location_types, headings, heading_tolerances, preferred_sides, approaches | array or string | — | Per point: pass a waypoint without stopping, set the direction of travel, or keep a stop on the curb side (approaches: curb). See Route Preferences. |
recostings | array | — | Price the route under up to five other costing models. See Recostings. |
Basic route
Section titled “Basic route”curl -X POST https://plaza.fyi/api/v1/route \ -H "x-api-key: pk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "origin": { "type": "Point", "coordinates": [2.3522, 48.8566] }, "destination": { "type": "Point", "coordinates": [2.2945, 48.8584] }, "mode": "auto" }'Response — a GeoJSON Feature with a LineString geometry:
{ "type": "Feature", "geometry": { "type": "LineString", "coordinates": [[2.3522, 48.8566], [2.3401, 48.8573], [2.2945, 48.8584]] }, "properties": { "distance_m": 4832, "duration_s": 743 }}| Mode | Uses |
|---|---|
auto | Roads from motorways down to service roads. No footways, paths or tracks. Follows one-way streets. |
foot | Every road and path except motorways and trunk roads, foot=no ways, and trails harder than max_hiking_difficulty (default: sac_scale=hiking). Takes steps. Ignores one-way streets. |
bicycle | Every road and path except motorways and platforms, and bicycle=no ways. Follows one-way streets unless bicycles may ride against them. |
Ways that are proposed, under construction or abandoned are never used. A route starts and ends at the nearest point of the network the mode can use, so a car is never placed on a sidewalk.
Routes follow OSM turn restrictions.
Travel speeds
Section titled “Travel speeds”duration_s is the time to travel each road at the mode’s speed, plus the time a car spends at junctions. Everything below is derived from OpenStreetMap tags and geometry. The class speeds, factors and delay sizes are modelled defaults taken from the OSRM and Valhalla routing engines, not measurements.
Cars drive at a speed for the road class, capped by the road’s speed limit:
| Road class | Car speed (km/h) |
|---|---|
| motorway | 90 |
| trunk | 85 |
| primary | 65 |
| secondary | 55 |
| tertiary | 40 |
| unclassified, residential, road | 25 |
| service | 15 |
| living_street | 10 |
Link roads are slower: 45 km/h for motorway_link down to 20 km/h for tertiary_link.
Bicycles ride at 15 km/h, 18 km/h on cycleways and 12 km/h on paths and tracks, also capped by the speed limit. On footways and pedestrian streets they go at walking pace (6 km/h), steps take 2 km/h, and ways tagged bicycle=dismount 5 km/h. People walk at 5 km/h. The bike type, cycling_speed and walking_speed change these, see Cycling and Walking Options.
Speed limits
Section titled “Speed limits”The limit is the road’s maxspeed, else zone:maxspeed, maxspeed:type or source:maxspeed. Plaza reads:
| Value | Read as |
|---|---|
50, 50 km/h | 50 km/h |
30 mph | 48 km/h |
10 knots | 19 km/h |
walk | 5 km/h |
none | 130 km/h |
DE:urban, FR:rural, IT:trunk, PL:motorway | that country’s default for urban roads, rural roads, trunk roads or motorways |
DE:zone30, DE:zone:30 | 30 km/h (mph for GB and US) |
GB:nsl_single, DE:living_street and similar | the national value |
50;30 | the lower one |
signals, variable and anything else Plaza can’t read count as no limit.
A road with no limit tagged gets its country’s legal default, from the OSM wiki’s default speed limits: the motorway limit on motorways, the urban limit on residential, living and service streets and on any road in a densely built-up area, the trunk limit on other trunk roads and the rural limit elsewhere. Plaza has defaults for about 40 countries, most of Europe plus the US, Canada, Japan, Australia, New Zealand, Mexico, Brazil, China and India. Mexico, Brazil, China and India use the national values the wiki lists. Brazil’s urban limit depends on the road: 30 km/h on residential and service streets, 60 km/h on primary, secondary and trunk roads in built-up areas, 40 km/h on other built-up roads. Plaza can also hold limits per state, but it has none yet, because the wiki lists none for these countries. Elsewhere, a road with no maxspeed keeps the class speed. The country comes from OSM’s national boundaries.
Surface and slope
Section titled “Surface and slope”Rough surfaces slow cars, trucks and bicycles, but not people on foot. Each surface keeps a share of the paved speed:
surface | Speed |
|---|---|
paving_stones | 90% |
compacted, fine_gravel | 80% |
cobblestone, sett | 70% |
gravel, pebblestone, unpaved | 60% |
dirt, earth, ground, grass | 45% |
sand | 30% |
mud | 15% |
On tracks, tracktype counts too, from 90% for grade1 to 30% for grade5. When a road has both tags, the slower one applies.
Where Plaza has elevation for a road (see Elevation), its average grade changes speed in the direction of travel:
- Cars keep 95% of their speed on a 2-4% climb, down to 75% at 8% or steeper. Trucks slow down more.
- Bicycles keep 85% on a 2-4% climb, 55% at 6%, 30% at 12% or steeper. Going down they gain up to 25%.
- Walking speed follows Tobler’s hiking function: fastest on a gentle descent, about 70% of the flat speed on a 10% climb.
The grade is averaged over each stretch of road between two junctions, from one end’s height to the other’s. Stretches shorter than 50 m count as flat, because the elevation data is too coarse for them.
Junctions and traffic signals
Section titled “Junctions and traffic signals”Car and truck times include the seconds spent at junctions. Plaza charges:
- Controlled nodes along a road: 4 s for a traffic light (up to 12 s in dense cities), 4 s for a stop sign, 2 s for a give-way sign, 3 s for a mini-roundabout (up to 8 s), 1 s for a pedestrian crossing and 15 s for a toll booth. Signals mapped on both sides of one junction count once. A node tagged
direction=forwardorbackward(ortraffic_signals:direction) only delays that direction. - Junctions where three or more roads meet: the average turn time over the ways out (sharp turns and turns across traffic cost more, U-turns most), scaled by priority. Straight through a quiet junction of equal streets costs about 2.5 s; staying on the main road costs a third of that, and arriving on a side road that meets it a little over twice. Signals, stop and give-way signs at the junction add 1-3 s. Left-hand-traffic countries mirror the turn costs. A road splitting into a dual carriageway is not a junction.
Junction waits grow up to 3.5 times in dense street networks, where traffic queues. The turn time is an average because routes are priced road by road, not turn by turn: going straight through a junction costs the same as turning there in duration_s. Which turn the route makes is steered separately, by turn costs. A trip that ends at a junction doesn’t wait there.
Bicycles and walkers don’t get these delays.
Access
Section titled “Access”Cars skip roads where motorcar, motor_vehicle or vehicle (else access) is no, private, agricultural or forestry, including lists of those such as agricultural;forestry. Roads where cars may only go to a destination (destination or delivery) or that are for customers stay usable, but the router adds 10 or 5 minutes when a route drives into one from an end, once however many junctions it passes on that road, so it only takes them when the trip starts or ends there. Turning into one from a cross street halfway along adds the same penalty as entering at its end. Service roads get 15 seconds, the same way. These penalties change which route wins, never duration_s.
One-way streets
Section titled “One-way streets”A road is one-way when it’s tagged oneway=yes (or -1 for the other direction), and roundabouts and motorways are one-way unless tagged oneway=no. A bicycle may ride against a one-way tagged oneway:bicycle=no, cycleway=opposite, opposite_lane or opposite_track, or with a two-way or contraflow cycle lane (cycleway:left:oneway=no or -1, and the same for right and both). oneway:bicycle=yes makes a road one-way for bicycles even when cars drive it both ways.
Turn restrictions
Section titled “Turn restrictions”Routes follow OpenStreetMap turn restrictions: relations tagged type=restriction with a from way, a via node (or one or more via ways) and a to way. Plaza reads no_left_turn, no_right_turn, no_straight_on, no_u_turn, no_entry and no_exit, plus only_left_turn, only_right_turn, only_straight_on and only_u_turn, which rule out every other way out of the junction, turning back included.
Who a restriction binds depends on the mode:
| Mode | Follows |
|---|---|
auto, truck, motorcycle, motor_scooter | restriction, unless except lists the vehicle (motorcar, hgv, motorcycle or moped), motor_vehicle or vehicle. The vehicle’s own key (restriction:motorcar, restriction:hgv, restriction:motorcycle, restriction:moped), then restriction:motor_vehicle and restriction:vehicle, take precedence. |
bicycle | restriction:bicycle and restriction:vehicle only. A plain restriction is almost always mapped for cars, and cyclists usually aren’t held to it. |
foot | restriction:foot only |
A route kept from a left turn goes round the block. When it has to avoid a restriction, it doesn’t turn back on the road it’s driving, except at a dead end: if the only legal way is to drive into a cul-de-sac and turn around, that’s the route you get, with the dead-end road listed twice. The turnaround costs no extra time beyond driving in and out. If the only way at all is the forbidden turn, the request returns no route.
restriction:conditional (and restriction:hgv:conditional and the like) understands two kinds of condition, alone or joined with AND:
- Time. Weekdays, times, months and dates, such as
no_left_turn @ (Mo-Fr 07:00-09:00,16:00-18:00),Sa,Su,22:00-06:00,Nov-MarorDec 24-Jan 02. A range can start or end atsunriseorsunset(sunset-sunrise,Mo-Fr sunrise-09:00), with an optional offset in parentheses ((sunset+00:30)-(sunrise-01:00)): Plaza works out the sun’s times at the junction on the day you leave. An offset never moves a time past midnight;(sunset+02:00)on a day the sun sets at 23:00 ends at midnight. These apply only withdepart_at, at that local time. Withoutdepart_at, no time condition applies. - Vehicle.
weight,length,height,width,axleloadandaxlescompared with>,>=,<or<=, such asno_left_turn @ (weight>7.5). Atruckis checked against its own dimensions. Cars count as 2 t, 4.7 m long, 1.6 m high and 1.9 m wide, soweight<3.5binds them andweight>7.5doesn’t; motorcycles and scooters get similar small figures. Bikes and walkers are never bound by these.
Sunrise and sunset are read on the local clock at the junction: Plaza works out the junction’s time zone and applies that zone’s rules on the day you leave, daylight saving included. Once the tz-boundaries dataset is loaded, the zone comes from its polygons, which follow county lines. Until then, and for a junction outside them, it comes from the country (and, in countries with several zones, its longitude and a few regional rules such as Arizona or Queensland). So a sunset-sunrise restriction in London starts at about 15:55 in December and 21:20 in June. Those country rules are accurate to state or province borders, not county lines, so a junction in a county on the other side of its state’s line (parts of Indiana, the Navajo Nation, Broken Hill in New South Wales, and so on) can get the neighbouring zone and times an hour off; a junction outside any known country uses UTC plus one hour per 15 degrees of longitude, with no daylight saving. A range can run past midnight on some days and not others (06:00-sunrise); Plaza decides that from the day’s sun times.
Public holidays work too. PH in the list of days makes the window hold on a holiday whatever the weekday (no_left_turn @ (Su,PH)), and a final PH off lifts the restriction on holidays (no_left_turn @ (Mo-Fr 07:00-09:00; PH off)). Plaza knows the holidays of Germany (by state, from the junction’s location), Austria, Switzerland (the days every canton keeps), France, the United Kingdom (by nation, with substitute days), the United States (federal holidays, on their observed weekdays), the Netherlands and Belgium. Elsewhere no day counts as a holiday, so Su,PH holds on Sundays only and PH off never lifts anything. The final PH off wins over a PH in an earlier rule, so Su,PH 10:00-12:00; PH off holds on Sundays that aren’t holidays. A PH off that isn’t the last rule is read as unsupported.
Conditions on school holidays (SH) or weather (wet, snow) are ignored, along with the whole entry they’re in.
Some restrictions have a from or to way that runs through the via node instead of starting or ending there. For no_left_turn, no_right_turn, no_straight_on, no_u_turn and their only_ forms, Plaza works out which side is meant from the angle of the turn. It skips the restriction when no side fits, or when more than one does. A U-turn restriction whose from and to are the same road through the junction forbids turning back there in both directions. no_entry and no_exit apply from both sides of such a road, as they do to several from or to roads.
Over a via way, Plaza pairs every piece of the from and to roads that touches the via ways. When more than one pair fits, it keeps the ones whose path runs along every via way. Then no_entry and no_exit keep all of them, and a restriction with a direction keeps the one pair that turns that way overall. Otherwise the restriction is skipped.
Restrictions carry across a waypoint. The leg leaving a stop can’t make a turn that the road the route arrived on forbids.
Turn costs
Section titled “Turn costs”Cars, trucks, motorcycles and scooters also pay a few seconds for turns drivers avoid when they can. These only choose the route. They are never part of duration_s.
| Turn | Cost |
|---|---|
| Across oncoming traffic: a left turn where traffic drives on the right, a right turn where it drives on the left (Hong Kong and Macau included, though OSM maps them inside China) | By the busiest other road bringing traffic into the junction: motorway or trunk 8 s, primary 6 s, secondary 4 s, tertiary 2 s, smaller roads nothing. A slip road counts as two classes smaller than its road |
| Onto a busier road, at a junction without traffic lights (on the junction or on one of its roads within about 55 m) | By the road you turn onto: motorway or trunk 6 s, primary 4 s, secondary 3 s, tertiary 2 s. Turning onto a slip road (*_link) costs nothing |
| U-turn from one road onto another at a junction, such as the far side of a dual carriageway | 10 s |
The costs add up, so turning left out of a side street onto a primary road costs 10 s. They apply only where three or more roads meet, never to a road that just carries on through the junction, and not at all on residential grids.
So a route may go round a block to avoid a left turn across a trunk road when that takes less than 8 s longer. The response still reports the real travel time of the block, not 8 s less. /matrix and alternative routes pay the same costs, and they pick the same route as /route. "shortest": true drops them, along with every other time-based preference. Isochrones don’t use them: an isochrone measures travel time, which turn costs don’t change. Neither does route optimization or the meeting point search, for the same reason. Leaving a waypoint is free of turn costs. maneuver_penalty adds on top of them.
With depart_at, car speeds are also scaled by the time-of-day profile. Truck routing has its own speeds.
Multi-waypoint routing
Section titled “Multi-waypoint routing”Pass waypoints to route through intermediate stops:
curl -X POST https://plaza.fyi/api/v1/route \ -H "x-api-key: pk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "origin": { "type": "Point", "coordinates": [2.3522, 48.8566] }, "destination": { "type": "Point", "coordinates": [2.3376, 48.8606] }, "waypoints": [ { "type": "Point", "coordinates": [2.3278, 48.8601] }, { "type": "Point", "coordinates": [2.2945, 48.8584] } ], "mode": "foot" }'The geometry is one line through every stop, and distance_m and duration_s are totals across all legs. waypoints can’t be combined with alternatives; the request fails with a 400.
Alternative routes
Section titled “Alternative routes”Set alternatives to get up to 3 routes ranked by duration:
curl -X POST https://plaza.fyi/api/v1/route \ -H "x-api-key: pk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "origin": { "type": "Point", "coordinates": [2.3522, 48.8566] }, "destination": { "type": "Point", "coordinates": [2.2945, 48.8584] }, "mode": "auto", "alternatives": 3 }'Returns a GeoJSON FeatureCollection. First feature is the fastest; the rest are sorted by duration. Every alternative follows the turn restrictions.
Turn-by-turn steps
Section titled “Turn-by-turn steps”Set "steps": true to get navigation steps in properties.steps. Each step starts with a maneuver and covers the travel up to the next one. Pick the instruction language with lang:
curl -X POST https://plaza.fyi/api/v1/route \ -H "x-api-key: pk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "origin": { "type": "Point", "coordinates": [2.3376, 48.8606] }, "destination": { "type": "Point", "coordinates": [2.3522, 48.8566] }, "steps": true, "lang": "fr" }'{ "type": "Feature", "geometry": { "type": "LineString", "coordinates": [[2.3376, 48.8606], [2.3522, 48.8566]] }, "properties": { "distance_m": 1520, "duration_s": 210, "steps": [ { "maneuver": { "type": "depart", "modifier": null, "instruction": "Dirigez-vous vers l'est sur Rue de Rivoli", "location": [2.3376, 48.8606], "bearing_before": null, "bearing_after": 112 }, "name": "Rue de Rivoli", "distance_m": 1200, "duration_s": 160 }, { "maneuver": { "type": "turn", "modifier": "right", "instruction": "Tournez à droite sur Rue du Renard", "location": [2.3511, 48.8574], "bearing_before": 112, "bearing_after": 175 }, "name": "Rue du Renard", "distance_m": 320, "duration_s": 50 }, { "maneuver": { "type": "arrive", "modifier": null, "instruction": "Vous êtes arrivé à destination", "location": [2.3522, 48.8566], "bearing_before": 175, "bearing_after": null }, "name": null, "distance_m": 0, "duration_s": 0 } ] }}The coordinates and distances above are illustrative. Steps work on every kind of route: direct, through waypoints, each of the alternatives, and EV routes.
| Step field | Description |
|---|---|
maneuver.type | depart, continue, new_name, turn, end_of_road, fork, uturn, on_ramp, off_ramp, merge, roundabout, exit_roundabout, rotary, exit_rotary, roundabout_turn, ferry, waypoint, charging_stop or arrive. |
maneuver.modifier | straight, slight_left, left, sharp_left, slight_right, right, sharp_right or uturn, from the angle between the two roads. null on depart, waypoint, charging_stop and arrive. |
maneuver.instruction | The instruction in the requested language. |
maneuver.location | Where the maneuver happens, [longitude, latitude]. |
maneuver.bearing_before, bearing_after | Heading in degrees from north before and after the maneuver. |
maneuver.exit | On a roundabout or rotary step, the exit you take: the exits you pass on the ring that the travel mode could use, plus one. Left out when the route ends on the ring. |
name | The street the step travels on, or null for an unnamed road. |
distance_m, duration_s | Distance and time to the next maneuver. Always metres and seconds, whatever units is. |
weight | Routing cost of the step. Plaza routes on time, so this equals duration_s. |
mode | driving, walking, cycling or ferry. |
leg_index | Which entry of properties.legs the step belongs to. |
geometry | The stretch of route from this maneuver to the next. See Navigation. |
intersections | The maneuver’s intersection, then every junction the step passes. |
ref, destinations, pronunciation | The road’s OSM ref, signposted destinations (destination:ref and destination) and name:pronunciation. Each one is only there when the road has the tag. |
exits | On an off_ramp, the exit number from the OSM highway=motorway_junction node where you leave (12A, or 12A;12B). |
rotary_name, rotary_pronunciation | On rotary and exit_rotary steps, the ring’s name and its name:pronunciation. |
driving_side | left or right: the side traffic keeps to in the step’s country. |
speed_limit_sign | mutcd (the US-style rectangle, used in the US, its territories and Canada) or vienna (the red circle used almost everywhere else). |
speed_limit_unit | mph or km/h. The road’s speed limit tag decides when it says (30 mph): maxspeed:forward or maxspeed:backward for the direction you travel, else maxspeed. Otherwise the country does. |
driving_side and the speed limit fields need the step’s country. Plaza takes it from OSM’s national boundaries (admin level 2). Hong Kong and Macau sit inside China’s boundary there but carry their own boundaries and codes, so a road inside them is HK or MO, with driving_side: left. Where a road has no OSM country, Plaza falls back to the Natural Earth countries datasets: the 1:10m one, which has Monaco, Singapore and the other microstates and is accurate to about a kilometre near borders, or the 1:110m one until the 1:10m one is loaded. If no source covers the road, the fields are left out. speed_limit_unit can still appear in that case, when the road’s own tag gives a unit.
Each leg ends with a step for the stop it reaches. A waypoint step marks one of your waypoints, numbered in order (“You have reached stop 1”). On an EV route, a charging_stop step marks each charging stop, and those don’t change the waypoint numbers. The last leg ends with arrive.
Street names come from OpenStreetMap. When a road has a name:<lang> tag for the requested language, that name is used; otherwise the local name, then the road number (ref).
How steps are built:
- A road carrying on through a junction stays one step. Consecutive roads with the same name form one step, unless the road turns by 60° or more. Two unnamed roads form one step only when they are the same kind of road (two residential streets, say) and the road goes on straight, turning by less than 20°.
- A roundabout step names the exit and the road you leave on (“At the roundabout, take the second exit onto Rue de Rivoli”). Entries, footways and one-way roads into the ring don’t count as exits.
- Going straight on onto a road with a different name is
new_name(“Continue onto Pine Street”).continueis for carrying on along the same street. - Leaving a motorway or trunk road onto a slip road is an
off_ramp(“Take exit 12A onto Main Street”). Entering a slip road from any other road is anon_ramp. Joining a motorway or trunk road from a slip road is amerge. - Where two or more roads you could take leave within 45° of straight ahead, and none of the others carries on the road you’re on, the step is a
forkwith modifierslight_left,slight_rightorstraight(“Keep left onto A 1”). - A left or right turn at a junction of three or more roads where nothing carries on within 30° of straight ahead is
end_of_road(“At the end of the road, turn left onto Oak Street”). - A turn at a mini-roundabout (
highway=mini_roundabout) is aroundabout_turn(“At the roundabout, turn left onto Oak Street”). - A roundabout whose ring has a name is a
rotary, with the name inrotary_name(“Enter Place Charles de Gaulle and take the third exit onto Avenue Foch”). - With
"roundabout_exits": true, the roundabout step covers only the ring and anexit_roundabout(orexit_rotary) step starts where you leave it (“Exit the roundabout onto Rue de Rivoli”).
Forks, ends of roads and mini-roundabouts come from the roads that meet at each junction. Without that data, for instance on a route whose graph was loaded before Plaza split roads at junctions, those steps fall back to turn and new_name.
Languages
Section titled “Languages”| Code | Language | Code | Language |
|---|---|---|---|
ar | Arabic | ja | Japanese |
da | Danish | ko | Korean |
de | German | nb | Norwegian Bokmål (no and nn also map here) |
en | English | nl | Dutch |
es | Spanish | pl | Polish |
fi | Finnish | pt | Portuguese |
fr | French | ru | Russian |
hi | Hindi | sv | Swedish |
id | Indonesian | th | Thai |
it | Italian | tr | Turkish |
vi | Vietnamese | zh | Chinese (Simplified) |
Without lang, the first language in the request’s Accept-Language header is used when it’s supported. Otherwise the instructions are in English, and an unsupported header language is never an error.
Only the first part of the tag picks the language, so pt-BR and pt-PT both get Portuguese and zh-Hans-CN gets Simplified Chinese. Traditional Chinese tags (zh-Hant, zh-TW, zh-HK) are rejected rather than answered in Simplified script. An explicit lang in any other language returns a 422 validation_error whose details.supported lists the codes above. lang is checked even when steps is off.
Arabic instructions wrap street names in the Unicode directional isolates U+2068 and U+2069, so a Latin name displays in the right order inside right-to-left text. The step’s name field has no isolates.
Every language except English is a machine translation that native speakers haven’t reviewed yet, so expect the odd awkward phrase.
Distances in instructions
Section titled “Distances in instructions”Distances inside instruction text follow units and the language’s decimal separator:
| Distance | units: "km" | units: "mi" |
|---|---|---|
| Under 1 km / 0.1 mi | metres, to the nearest 10 (250 m; to the metre under 10 m) | feet, to the nearest 10 (330 ft) |
| Under 10 km / 10 mi | one decimal (1.2 km, 1,2 km in German) | one decimal (0.7 mi) |
| Longer | whole numbers (12 km) | whole numbers (15 mi) |
In the United Kingdom and the Crown Dependencies (Guernsey, Jersey, the Isle of Man), where road signs give short distances in yards, mi uses yards instead of feet under 0.1 mi, to the nearest 10 (In 150 yd, turn left), as Mapbox’s navigation SDKs do. The step’s country decides, so a route from Dover to Calais switches from yards to feet at the border. voice_units: "imperial" follows the same rule.
Spoken variants
Section titled “Spoken variants”Add "verbal": true to get four more strings on each maneuver, meant for voice guidance and compact UIs:
| Field | When to use it | Example (lang: "en") |
|---|---|---|
verbal_alert | Early warning, without the street | Turn left |
verbal_pre | Just before the maneuver, with the distance to it | In 1.8 km, turn left onto Oak Avenue |
verbal_post | Just after the maneuver, with the distance to the next one (null on arrival) | Continue on Oak Avenue for 1.1 km |
verbal_succinct | Tight spaces | Left on Oak Avenue |
Navigation
Section titled “Navigation”With steps, a route also has what a turn-by-turn app needs: a line per step, the junctions along it, lanes, and voice and banner text. Build a Turn-by-Turn Nav App walks through using them: following the driver along the steps, timing the announcements, and re-routing when they leave the route. Turn on the extras you want:
curl -X POST https://plaza.fyi/api/v1/route \ -H "x-api-key: pk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "origin": { "type": "Point", "coordinates": [-122.430, 37.770] }, "destination": { "type": "Point", "coordinates": [-122.400, 37.780] }, "steps": true, "voice_instructions": true, "banner_instructions": true, "annotations": true, "waypoint_names": ["", "Office"] }'The route’s properties then also include:
| Field | Description |
|---|---|
legs | One per stretch between stops: distance_m, duration_s, weight, a summary naming the two roads used longest, and with annotations the per-coordinate arrays below. |
waypoints | Origin, each stop and destination as snapped to the road network: name (the street there), location and distance_m from the point you sent. EV routes leave out distance_m, because their legs include charging stops you didn’t send. |
admins | The countries the route passes through, in order: iso_3166_1 (DE) and iso_3166_1_alpha3 (DEU). Intersections point into this list with admin_index. Empty when no country is known for the route’s roads. |
weight, weight_name | Routing cost of the whole route and what it measures (always duration). |
voice_locale | The language of the voice announcements, with voice_instructions. |
Step geometry
Section titled “Step geometry”Each step’s geometry is its piece of the route line, in the request’s geometries format. Within a leg the steps join end to end: drop each step’s first point (it’s the previous step’s last) and you get the leg’s line back. Arrival steps are a two-point line at the arrival point. Step geometries keep every point even with overview: "simplified" or false.
Intersections
Section titled “Intersections”{ "location": [-122.41, 37.77], "bearings": [0, 90, 180, 270], "entry": [true, true, false, false], "in": 3, "out": 0, "geometry_index": 1, "lanes": [ { "indications": ["left"], "valid": true, "active": true, "valid_indication": "left" }, { "indications": ["straight"], "valid": false, "active": false } ]}| Field | Description |
|---|---|
bearings | Heading of each road leaving the junction, degrees from north, sorted. |
entry | Whether the route could take each road. A road is closed to you if it’s one-way towards the junction under the mode’s one-way rules, access=no or private, or off limits to the mode, such as motorways on foot. The road you arrived on is always false. |
in, out | Index in bearings of the road you arrive on and the road you take. A depart has only out and an arrival only in. |
geometry_index | Index of the junction in the leg’s coordinates. |
classes | What applies to the road taken: toll, ferry, restricted, motorway, tunnel (with tunnel_name). Left out when nothing applies. |
lanes | From the approaching road’s OSM turn:lanes, left to right. valid lanes work for the turn the route takes. active is the same as valid here, because Plaza doesn’t look ahead to the next maneuver. |
toll_collection | A toll point: { "type": "toll_booth" } for barrier=toll_booth, { "type": "toll_gantry" } for highway=toll_gantry, with name when tagged. |
rest_stop | A motorway or trunk slip road leaving here runs into a rest area or service area (highway=rest_area or highway=services): { "type": "rest_area" | "service_area", "name": "…" }. |
admin_index | Index in properties.admins of the country of the road taken. Left out when the country isn’t known. |
is_urban | Whether the road taken is in a built-up area, from the density of the road network around it. Roads whose density hasn’t been computed yet count as urban, as they do in the traffic profiles. |
Plaza’s routing graph splits roads at every node they share with another road, so every road that meets the route at a junction shows up. A road that crosses without a shared node, such as a bridge over the route, doesn’t.
A toll booth or gantry usually sits in the middle of a road, not at a junction. It still gets its own intersection, with just the road you arrive on and the road you leave on, so you can show it as the route reaches it.
Voice instructions
Section titled “Voice instructions”Each step’s voice_instructions announce the maneuver at the end of that step. distance_along_geometry_m is how far before the maneuver to speak, so it counts down along the step. The list is farthest first:
[ { "distance_along_geometry_m": 1760, "announcement": "Head east on Main Street", "ssml_announcement": "<speak>Head east on <say-as interpret-as=\"address\">Main Street</say-as></speak>" }, { "distance_along_geometry_m": 500, "announcement": "In 500 m, turn left onto Oak Avenue", "ssml_announcement": "…" }, { "distance_along_geometry_m": 80, "announcement": "Turn left onto Oak Avenue", "ssml_announcement": "…" }]| Mode | Early warning (metric / imperial) | Final call |
|---|---|---|
auto, truck, motorcycle, motor_scooter | 500 m / 0.5 mi | 80 m |
bicycle | 200 m / 0.1 mi | 30 m |
foot | 100 m / 300 ft | 15 m |
The first step also announces the departure. A step more than twice the early-warning distance long starts with “Continue on … for …”. The early warning is skipped when the step is shorter than 1.25 times its distance, and the final call moves to the start of a step shorter than the final-call distance. Announcements follow lang, and their distances follow voice_units (default: units). The SSML version marks street names as addresses and escapes XML characters.
Banner instructions
Section titled “Banner instructions”Each step’s banner_instructions hold one banner for the maneuver at the end of the step, shown for the whole step:
{ "distance_along_geometry_m": 1760, "primary": { "text": "Oak Avenue / CA 1", "type": "turn", "modifier": "left", "components": [ { "text": "Oak Avenue", "type": "text" }, { "text": "/", "type": "delimiter" }, { "text": "CA 1", "type": "icon" } ] }, "secondary": { "text": "Golden Gate Bridge", "components": [{ "text": "Golden Gate Bridge", "type": "text" }] }, "sub": { "text": "", "components": [ { "text": "", "type": "lane", "active": true, "active_direction": "left", "directions": ["left"] }, { "text": "", "type": "lane", "active": false, "directions": ["straight"] } ] }}The names in this example are made up. primary names the road after the maneuver, with its ref as an icon component. If the road has no name, primary shows the instruction text instead. On an off_ramp at a numbered exit, primary starts with an exit component (the word on the sign in lang, such as “Exit” or “Ausfahrt”) and an exit-number component for each number: "Exit 12A Main Street". Onto an unnamed slip road the banner is just the sign, "Exit 12A". secondary is only there when the road has signposted destinations, and sub only when there are lanes. Plaza doesn’t host shield images, so icon components have no image_base_url. Draw your own shield from the text.
Leg annotations
Section titled “Leg annotations”With annotations: true, each leg has arrays with one entry per pair of consecutive coordinates of the leg’s line: distance_m, duration_s, speed_ms, maxspeed ({ "speed": 50, "unit": "km/h" }, in mph when the road is tagged in mph, or { "unknown": true }) and road_class (the OSM highway value). An edge’s length and time are split across its coordinate pairs by length, so they add up to the edge.
The same arrays carry congestion:
| Array | Description |
|---|---|
freeflow_speed_kmh | The mode’s speed on that road with no traffic and no junction delays. |
current_speed_kmh | The speed at your depart_at hour, from Plaza’s time-of-day traffic profiles. null without depart_at, and for walking and cycling. |
congestion_numeric | How much the profile slows the road: 0 is free flow, 100 is stopped. null without a profile. |
congestion | The same as a level: low (under 40), moderate (40–59), heavy (60–79), severe (80 and up), or unknown without a profile. |
These are modelled speeds for that hour and weekday, not live traffic. Plaza doesn’t have a live traffic feed yet.
Named stops
Section titled “Named stops”waypoint_names gives the arrival instructions a name: “You have arrived at Office” instead of “You have arrived at your destination”, and “You have reached Bakery” instead of “You have reached stop 1”. Send one entry per point, origin first. Use null or "" for points that keep the default text, such as the origin.
Coming from Mapbox Directions
Section titled “Coming from Mapbox Directions”Plaza uses the field vocabulary of Mapbox Directions v5, so most of a Mapbox navigation client carries over. The differences:
| Mapbox | Plaza |
|---|---|
routes[] envelope | A GeoJSON Feature, or a FeatureCollection with alternatives |
routes[].distance, duration | properties.distance_m, duration_s |
routes[].weight, weight_name | properties.weight, weight_name (duration) |
routes[].legs[].steps | properties.steps, one list for all legs, each step with leg_index |
routes[].legs[].summary | properties.legs[].summary |
routes[].legs[].annotation | properties.legs[].annotations (distance_m, duration_s, speed_ms, maxspeed, road_class, freeflow_speed_kmh, current_speed_kmh, congestion, congestion_numeric) |
routes[].legs[].admins | properties.admins, one list for the whole route |
waypoints[] | properties.waypoints[] |
language | lang (BCP 47) |
voice_units, voice_instructions, banner_instructions, roundabout_exits, waypoint_names, approaches | Same names |
steps[].maneuver.modifier "slight left" | "slight_left" (underscores) |
on ramp, off ramp, new name, end of road, roundabout turn | on_ramp, off_ramp, new_name, end_of_road, roundabout_turn |
exit roundabout, exit rotary | exit_roundabout, exit_rotary |
notification (ferry) | ferry |
voiceInstructions[].distanceAlongGeometry | voice_instructions[].distance_along_geometry_m |
bannerInstructions[] | banner_instructions[] |
steps[].distance, duration | distance_m, duration_s |
Not available yet: shield images and junction views. exclude=cash_only_tolls works as described under cash-only tolls. Plaza has no live traffic feed, so current_speed_kmh and congestion come from fixed time-of-day profiles, and only when you send depart_at.
Annotations
Section titled “Annotations”Pass "annotations": true to get per-edge metadata (speed, duration, surface) in properties.annotations and properties.edges. It’s off by default.
Encoded polylines
Section titled “Encoded polylines”Set "geometries": "polyline" or "polyline6" to get the route as an encoded string instead of GeoJSON coordinates. The string is in properties.polyline, and geometry is null:
curl -X POST https://plaza.fyi/api/v1/route \ -H "x-api-key: pk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "origin": { "type": "Point", "coordinates": [2.3522, 48.8566] }, "destination": { "type": "Point", "coordinates": [2.2945, 48.8584] }, "geometries": "polyline6" }'{ "type": "Feature", "geometry": null, "properties": { "distance_m": 4832, "duration_s": 743, "polyline": "_p~iF~ps|U_ulLnnqC" }}The polyline value is an illustrative placeholder. With "overview": false there’s no geometry at all.
Departure time
Section titled “Departure time”depart_at slows each road by its typical congestion at that hour and weekday. A timestamp with Z or an offset is an exact instant, converted to local time at the origin; one without an offset is local time at the origin as written. "now" is read on the origin’s local clock. Daylight saving is included in each case. There is no live traffic. Traffic-Aware Routing has the details and the speed profiles.
curl -X POST https://plaza.fyi/api/v1/route \ -H "x-api-key: pk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "origin": { "type": "Point", "coordinates": [2.3522, 48.8566] }, "destination": { "type": "Point", "coordinates": [2.2945, 48.8584] }, "mode": "auto", "depart_at": "2026-03-23T08:30:00+01:00" }'Conditional limits
Section titled “Conditional limits”depart_at also picks which time-dependent road limits are in force. Take a school street tagged
motor_vehicle:conditional = no @ (Mo-Fr 07:30-09:00,14:30-16:00)A car route leaving at 08:00 on a Monday goes around it. The same route on Saturday, or at 10:00, drives through.
Plaza reads access:conditional, vehicle:conditional, motor_vehicle:conditional, motorcar:conditional, hgv:conditional, motorcycle:conditional, moped:conditional, bicycle:conditional, foot:conditional and maxspeed:conditional. Trucks also get maxweight:conditional, maxheight:conditional, maxwidth:conditional, maxlength:conditional and maxaxleload:conditional. Conditions are the ones conditional turn restrictions take: weekdays, times, months and dates, sunrise and sunset, public holidays, and vehicle properties such as weight>7.5. When several entries hold, the more specific key wins (motorcar over motor_vehicle over access), then the one written last. A conditional destination, delivery or customers value adds the same 10 or 5 minutes as the plain tag (see Access) while it holds, and a conditional yes on such a road drops them. Public holidays (PH) come from the same list: the road’s own state in Germany, its own nation in the United Kingdom, and its country everywhere else. An entry with a condition Plaza can’t check, such as wet, snow or SH, is skipped.
Without depart_at, every road keeps its plain value. The school street is open at any hour, and maxspeed:conditional = 30 @ (22:00-06:00) never lowers the limit. Matrices and isochrones take depart_at too, and apply the same conditional limits at that time.
Excluding road types
Section titled “Excluding road types”Avoid tolls, ferries, or specific road classes:
curl -X POST https://plaza.fyi/api/v1/route \ -H "x-api-key: pk_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "origin": { "type": "Point", "coordinates": [2.3522, 48.8566] }, "destination": { "type": "Point", "coordinates": [2.2945, 48.8584] }, "mode": "auto", "exclude": "toll,ferry" }'To lean away from tolls or highways without banning them, use the use_* preferences in Route Preferences.
Cash-only tolls
Section titled “Cash-only tolls”exclude: "cash_only_tolls" avoids every road through a toll booth (barrier=toll_booth) that takes only cash. A booth counts as cash-only when its payment:cash, payment:coins or payment:notes is yes and no other payment:* tag is yes, such as payment:credit_cards or payment:e_zpass. A booth with no payment tags of its own is judged by the toll road through it (toll=yes) by the same rule. A booth with no payment tags on either isn’t cash-only, so routes still pass it. POST /api/v1/matrix, /isochrone, /centroid, /optimize, /expansion and /map-match take the same exclude.
{"origin": {"type": "Point", "coordinates": [-74.006, 40.7128]}, "destination": {"type": "Point", "coordinates": [-73.9857, 40.7484]}, "exclude": "cash_only_tolls"}Avoiding areas
Section titled “Avoiding areas”Upload the areas you want to stay out of (flood zones, closures, a stadium on game day) as polygons in a dataset, then name it in avoid_datasets:
curl -X POST https://plaza.fyi/api/v1/route \ -H "x-api-key: $PLAZA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "origin": { "type": "Point", "coordinates": [-74.0060, 40.7128] }, "destination": { "type": "Point", "coordinates": [-73.9855, 40.7580] }, "avoid_datasets": ["flood-zones"] }'Every road segment that touches one of the dataset’s polygons is left out of the graph. Point and line features are ignored. If the origin or destination sits inside an avoided polygon, or there’s no way around, the answer is a 404 No route found. The option applies to every leg, alternative and EV plan. /isochrone, /matrix, /centroid, /optimize and /expansion take it too, and /map-match never snaps a point to a road that touches one of the polygons.
Name up to 10 datasets by slug or ID, yours or Plaza-curated. Any other dataset answers 404 dataset not found. The "plaza" and "all" keywords are a 400 here: routing around every Census county is not something a road network survives. Together the datasets may hold at most 1,000 polygons and 200,000 vertices; more is a 422, so simplify or split big areas first. The request stays a premium request.
Your own roads
Section titled “Your own roads”OpenStreetMap doesn’t have every road. A campus, a private estate, a mine site or a road that opened last week may be missing. Upload those roads as line features in a dataset and name it in datasets:
curl -X POST https://plaza.fyi/api/v1/route \ -H "x-api-key: $PLAZA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "origin": { "type": "Point", "coordinates": [-122.1697, 37.4275] }, "destination": { "type": "Point", "coordinates": [-122.1730, 37.4300] }, "datasets": ["campus-roads"] }'A line feature counts as a road when it has a highway property (or road_class) with an OpenStreetMap value such as residential or service; cars skip classes OSM doesn’t use for roads. Plaza reads the rest of its properties the way it reads OSM tags: maxspeed, oneway, access, motor_vehicle, foot, bicycle, surface, toll and friends. So a highway: "footway" carries walkers but not cars, access: "private" keeps cars off, and duration_s is timed exactly as on an OSM road of that class.
Your roads join the OSM network where one of their ends is within 10 m of an OSM junction. Plaza makes that link when it processes your upload, so draw the ends on the junctions. Elsewhere a road only connects to the other roads in your dataset. A few things don’t carry over: OSM turn restrictions and turn costs, traffic profiles and intersection delays. Their edges in the response have osm_way_id: null, and turn-by-turn instructions name them by their name property.
Name up to 20 datasets by slug or ID, yours or Plaza-curated. Any other dataset answers 404 dataset not found, and "plaza" and "all" are a 400. datasets applies to every leg, alternative and EV plan, and /isochrone, /matrix, /map-match, /optimize, /centroid, /expansion and /nearest take it too. It doesn’t work with mode: "transit". Don’t confuse it with avoid_datasets: that one names polygons to stay out of. The request stays a premium request.
PlazaQL
Section titled “PlazaQL”Directions are also available in PlazaQL:
$r = route(origin: point(48.8566, 2.3522), destination: point(48.8584, 2.2945), mode: "auto");
// Find gas stations along the routesearch(amenity: "fuel") .around(distance: 500, geometry: $r);route() takes waypoints, alternatives, depart_at, traffic_model, exclude, avoid_datasets, datasets, steps, lang, units, verbal, voice_instructions, banner_instructions, roundabout_exits, voice_units, waypoint_names and the route preferences too, with the same values and the same validation as the REST body. In PlazaQL, waypoint_names is a list of strings, with "" for no name:
route( origin: point(48.8566, 2.3522), destination: point(48.8584, 2.2945), depart_at: "2026-03-23T08:30:00", exclude: ["toll"]);Turn-by-turn steps in German:
route( origin: point(52.5163, 13.3777), destination: point(52.5219, 13.4132), steps: true, lang: "de");Navigation output with voice and banner instructions:
route( origin: point(37.770, -122.430), destination: point(37.780, -122.400), steps: true, voice_instructions: true, banner_instructions: true, voice_units: "imperial", waypoint_names: ["", "Office"]);