---
title: Directions | Plaza Docs
description: Turn-by-turn directions between points. Car, foot, and bicycle modes with alternative routes, waypoints, and step-by-step navigation.
---

The Directions API computes routes on the full OSM road and path network, returning a GeoJSON LineString geometry with distance, duration, and turn-by-turn steps.

Directions is a [premium endpoint](/guides/authentication#premium-endpoints/index.md) — each request counts as 4x.

## Endpoint

```
POST /api/v1/route
```

## 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`, or `bicycle`.                                                                                |
| `waypoints`    | GeoJSON Point\[] | —           | Intermediate stops (max 25). Route visits them in order.                                                                  |
| `alternatives` | int              | `0`         | Number of alternative routes (0–3).                                                                                       |
| `steps`        | boolean          | `false`     | Include turn-by-turn navigation steps.                                                                                    |
| `annotations`  | boolean          | `false`     | Include per-edge metadata (speed, duration, surface).                                                                     |
| `overview`     | string           | `"full"`    | Geometry detail: `full`, `simplified`, or `false`.                                                                        |
| `geometries`   | string           | `"geojson"` | Encoding: `geojson`, `polyline`, or `polyline6`.                                                                          |
| `exclude`      | string           | —           | Comma-separated road types to avoid: `toll`, `ferry`, `unpaved`, `motorway`, `trunk`, `primary`, `secondary`, `tertiary`. |

## Basic route

Terminal window

```
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"
  }'
```

```
import Plaza from "@plazafyi/sdk";


const client = new Plaza();


const route = await client.v1.route({
  origin: { type: "Point", coordinates: [2.3522, 48.8566] },
  destination: { type: "Point", coordinates: [2.2945, 48.8584] },
  mode: "auto",
});


console.log(`${route.properties.distance_m}m in ${route.properties.duration_s}s`);
```

```
import plaza


client = plaza.Client()


route = client.v1.route(
    origin={"type": "Point", "coordinates": [2.3522, 48.8566]},
    destination={"type": "Point", "coordinates": [2.2945, 48.8584]},
    mode="auto",
)
print(f"{route['properties']['distance_m']}m in {route['properties']['duration_s']}s")
```

```
import "github.com/plazafyi/plaza-go"


client := plaza.NewClient()


route, _ := client.V1.Route(ctx, plaza.RouteParams{
    Origin:      plaza.GeoJSONPoint{Type: "Point", Coordinates: []float64{2.3522, 48.8566}},
    Destination: plaza.GeoJSONPoint{Type: "Point", Coordinates: []float64{2.2945, 48.8584}},
    Mode:        "auto",
})
fmt.Printf("%dm in %ds\n", route.Properties.DistanceM, route.Properties.DurationS)
```

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
  }
}
```

## Modes

| Mode      | Uses                                                                  |
| --------- | --------------------------------------------------------------------- |
| `auto`    | Roads. Respects one-ways, turn restrictions, road class.              |
| `foot`    | Sidewalks, footpaths, pedestrian zones. Ignores one-way restrictions. |
| `bicycle` | Bike lanes, cycleways, shared roads. Avoids motorways.                |

## Multi-waypoint routing

Pass `waypoints` to route through intermediate stops:

Terminal window

```
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 response includes per-leg breakdowns in `properties.legs` (each with `distance_m`, `duration_s`, and `steps`). Top-level values are totals.

## Alternative routes

Set `alternatives` to get up to 3 routes ranked by duration:

Terminal window

```
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.

## Steps and annotations

Pass `"steps": true` for turn-by-turn directions, or `"annotations": true` for per-edge metadata. Both are off by default.

## Excluding road types

Avoid tolls, ferries, or specific road classes:

Terminal window

```
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"
  }'
```

## PlazaQL

Directions are also available in [PlazaQL](/guides/plazaql/routing-geocoding-search/index.md):

```
$r = route(origin: point(48.8566, 2.3522), destination: point(48.8584, 2.2945), mode: "auto");


// Find gas stations along the route
search(amenity: "fuel")
  .around(distance: 500, geometry: $r);
```