# Directions

Turn-by-turn routes between 2-25 waypoints, for driving (with or without live traffic), walking, or cycling, from the [Directions API](https://docs.mapbox.com/api/navigation/directions/). The electric-vehicle routing parameters (`engine=electric` and everything under it) aren't exposed. The command also takes the common flags — `--username`/`-u`, `--token`/`-t`, `--profile`, `--id` — described in [Shared parameters](https://docs.mapbox.com/cli/reference/#shared-parameters).

For travel times between every pair of a set of points rather than one route through them, see [`mapbox matrix`](https://docs.mapbox.com/cli/reference/matrix/).

-   [`mapbox directions`](#mapbox-directions)

## `mapbox directions`

A route through the waypoints in the order given — a route through fixed stops, not a traveling-salesman solve.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `<routing-profile>` | Required. `mapbox/driving-traffic` (accounts for live traffic), `mapbox/driving`, `mapbox/walking`, or `mapbox/cycling`. Sent as typed rather than checked against a list, since some accounts have additional profiles of their own. |
| `<coordinates>` | Required. 2-25 `{longitude},{latitude}` pairs, semicolon-separated. The route visits them in this order. A leading `-` on a longitude isn't mistaken for a flag. |
| `--alternatives` | Return up to 2 alternative routes alongside the primary one. |
| `--annotations` | Segment-level metadata per leg, comma-separated: `distance`, `duration`, `speed`, `congestion`, `congestion_numeric`, `maxspeed`, `closure`, `state_of_charge`. Requires `--overview full`. |
| `--avoid-maneuver-radius` | Radius in meters, 1-1000, around the start point within which to avoid a significant maneuver. |
| `--bearings` | An `{angle},{degrees}` per waypoint, semicolon-separated, filtering road segments by direction of travel. |
| `--layers` | A signed integer per waypoint, semicolon-separated, selecting a road layer (Z-order) on a multi-level road. |
| `--continue-straight` | Keep going straight at an intermediate waypoint rather than u-turning back to it, even if that is faster. |
| `--exclude` | Road types or `point(lon lat)` values to route around, comma-separated: `motorway`, `toll`, `ferry`, `unpaved`, `cash_only_tolls`, `country_border`, `state_border`, `tunnel`. |
| `--geometries` | Route geometry format. Defaults to `polyline`. Values: `geojson`, `polyline`, `polyline6`. |
| `--include` | Special road types to allow, comma-separated: `hov2`, `hov3`, `hot`. |
| `--overview` | How much geometry detail the response carries. Defaults to `simplified`. Values: `full`, `simplified`, `false`. |
| `--radiuses` | Maximum distance in meters each coordinate may snap to the road network, semicolon-separated: a number or `unlimited` per coordinate. |
| `--approaches` | Which side of the road to approach each waypoint from, semicolon-separated: `unrestricted` or `curb` per coordinate. |
| `--steps` | Return turn-by-turn instructions. Several parameters below only take effect with this set. |
| `--banner-instructions` | Return banner objects for display. Requires `--steps`. |
| `--language` | The language of turn-by-turn instructions. Defaults to `en`. Requires `--steps`. |
| `--roundabout-exits` | Separate instructions for entering and exiting a roundabout. Requires `--steps`. |
| `--voice-instructions` | Return SSML-marked-up voice guidance text. Requires `--steps`. |
| `--voice-units` | Units for voice instructions. Requires `--steps` and `--voice-instructions`. Values: `imperial`, `british_imperial`, `metric`. |
| `--waypoints` | Zero-based indices of the coordinates that get their own arrival instruction. Must include `0` and the last index. Requires `--steps`. |
| `--waypoints-per-route` | Nest each route's waypoints under that route instead of once at the top level. |
| `--waypoint-names` | A name per waypoint, semicolon-separated, used in its arrival instruction instead of the road name. Requires `--steps`. |
| `--waypoint-targets` | A `{longitude},{latitude}` drop-off point per waypoint, semicolon-separated, when it differs from the routed-to coordinate. Requires `--steps`. |
| `--notifications` | Whether to return route notification and warning metadata. Values: `all`, `none`. |
| `--alley-bias` | Bias the route against (negative) or toward (positive) alleys, `-1` to `1`. `mapbox/driving` only. |
| `--arrive-by` | Desired arrival time, ISO 8601. `mapbox/driving` only. |
| `--depart-at` | Departure time, ISO 8601. For `mapbox/driving` it drives time-dependent routing; for `mapbox/driving-traffic` it selects which traffic conditions to route against. |
| `--max-height` | Vehicle height in meters, 0-10. Defaults to `1.6`. `mapbox/driving` and `mapbox/driving-traffic` only. |
| `--max-width` | Vehicle width in meters, 0-10. Defaults to `1.9`. `mapbox/driving` and `mapbox/driving-traffic` only. |
| `--max-weight` | Vehicle weight in metric tons, 0-100. Defaults to `2.5`. `mapbox/driving` and `mapbox/driving-traffic` only. |
| `--snapping-include-closures` | Allow snapping to roads with a live-traffic closure. `mapbox/driving-traffic` only. |
| `--snapping-include-static-closures` | Allow snapping to roads with a long-term closure. `mapbox/driving-traffic` only. |
| `--walking-speed` | Walking speed in meters per second, 0.14-6.94. Defaults to `1.42`. `mapbox/walking` only. |
| `--walkway-bias` | Bias the route against (negative) or toward (positive) walkways and footpaths, `-1` to `1`. `mapbox/walking` only. |

**Examples:**

```sh
mapbox directions mapbox/driving "-122.42,37.78;-122.45,37.91"
mapbox directions mapbox/driving-traffic "-122.42,37.78;-122.45,37.91" --alternatives
mapbox directions mapbox/walking "-122.42,37.78;-122.43,37.79" \
  --steps --geometries geojson --overview full --annotations distance,duration
```