Directions

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 — 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

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:

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:

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:

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:

$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);