Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference
Routing

Calculate a route between two points

POST/api/v1/route

Calculate a route between two points

Query ParametersExpand Collapse
format: optional string

Response format for alternatives: json (default), geojson, csv, ndjson

Body ParametersJSONExpand Collapse
destination: object { lat, lng }

Geographic coordinate as a JSON object with lat and lng fields.

lat: number

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: number

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
origin: object { lat, lng }

Geographic coordinate as a JSON object with lat and lng fields.

lat: number

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: number

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
alternatives: optional number

Number of alternative routes to return (0-3, default 0). When > 0, response is a FeatureCollection of route Features.

maximum3
minimum0
annotations: optional boolean

Include per-edge annotations (speed, duration) on the route (default: false)

depart_at: optional string

Departure time for traffic-aware routing (ISO 8601)

formatdate-time
ev: optional object { battery_capacity_wh, connector_types, initial_charge_pct, 2 more }

Electric vehicle parameters for EV-aware routing

battery_capacity_wh: number

Total battery capacity in watt-hours (required for EV routing)

connector_types: optional array of string

Acceptable connector types (e.g. ["ccs", "chademo"])

initial_charge_pct: optional number

Starting charge as a fraction 0-1 (default: 0.8)

maximum1
minimum0
min_charge_pct: optional number

Minimum acceptable charge at destination as a fraction 0-1 (default: 0.10)

maximum1
minimum0
min_power_kw: optional number

Minimum charger power in kilowatts

exclude: optional string

Comma-separated road types to exclude (e.g. toll,motorway,ferry)

geometries: optional "geojson" or "polyline" or "polyline6"

Geometry encoding format. Default: geojson.

One of the following:
"geojson"
"polyline"
"polyline6"
mode: optional "auto" or "foot" or "bicycle"

Travel mode (default: auto)

One of the following:
"auto"
"foot"
"bicycle"
overview: optional "full" or "simplified" or "false"

Level of geometry detail: full (all points), simplified (Douglas-Peucker), false (no geometry). Default: full.

One of the following:
"full"
"simplified"
"false"
steps: optional boolean

Include turn-by-turn navigation steps (default: false)

traffic_model: optional "best_guess" or "optimistic" or "pessimistic"

Traffic prediction model (only used when depart_at is set)

One of the following:
"best_guess"
"optimistic"
"pessimistic"
waypoints: optional array of object { lat, lng }

Intermediate waypoints to visit in order (maximum 25)

lat: number

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: number

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
ReturnsExpand Collapse
RouteResult = object { geometry, properties, type }

GeoJSON Feature representing a calculated route. The geometry is a LineString or MultiLineString of the route path. When alternatives > 0, the response is a FeatureCollection containing multiple route Features.

geometry: GeoJsonGeometry { coordinates, type }

GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number

Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

One of the following:
Point = array of number

[longitude, latitude] or [longitude, latitude, elevation]

LineStringOrMultiPoint = array of array of number

Array of [lng, lat] positions

PolygonOrMultiLineString = array of array of array of number

Array of linear rings / line strings

MultiPolygon = array of array of array of array of number

Array of polygons

type: "Point" or "LineString" or "Polygon" or 3 more

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: object { distance_m, duration_s, annotations, 4 more }

Route metadata

distance_m: number

Total route distance in meters

duration_s: number

Estimated travel duration in seconds

annotations: optional map[unknown]

Per-edge annotations (present when annotations: true in request)

charge_profile: optional array of array of number

Battery charge level at route waypoints as [distance_fraction, charge_pct] pairs (EV routes only)

charging_stops: optional array of map[unknown]

Recommended charging stops along the route (EV routes only)

edges: optional array of map[unknown]

Edge-level route details (present when annotations: true)

energy_used_wh: optional number

Total energy consumed in watt-hours (EV routes only)

type: "Feature"

Calculate a route between two points

curl https://plaza.fyi/api/v1/route \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $PLAZA_API_KEY" \
    -d '{
          "destination": {
            "lat": 48.8584,
            "lng": 2.2945
          },
          "origin": {
            "lat": 48.8566,
            "lng": 2.3522
          }
        }'
{
  "geometry": {
    "coordinates": [
      2.3522,
      48.8566
    ],
    "type": "Point"
  },
  "properties": {
    "distance_m": 4523.7,
    "duration_s": 847.2,
    "annotations": {
      "foo": "bar"
    },
    "charge_profile": [
      [
        0
      ]
    ],
    "charging_stops": [
      {
        "foo": "bar"
      }
    ],
    "edges": [
      {
        "foo": "bar"
      }
    ],
    "energy_used_wh": 0
  },
  "type": "Feature"
}
Returns Examples
{
  "geometry": {
    "coordinates": [
      2.3522,
      48.8566
    ],
    "type": "Point"
  },
  "properties": {
    "distance_m": 4523.7,
    "duration_s": 847.2,
    "annotations": {
      "foo": "bar"
    },
    "charge_profile": [
      [
        0
      ]
    ],
    "charging_stops": [
      {
        "foo": "bar"
      }
    ],
    "edges": [
      {
        "foo": "bar"
      }
    ],
    "energy_used_wh": 0
  },
  "type": "Feature"
}