Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference
Routing

Calculate a route between two points

$ plaza routing route
POST/api/v1/route

Calculate a route between two points

ParametersExpand Collapse
--destination: object { lat, lng }

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

--origin: object { lat, lng }

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

--format: optional string

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

--alternatives: optional number

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

--annotations: optional boolean

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

--depart-at: optional string

Body param: Departure time for traffic-aware routing (ISO 8601)

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

Body param: Electric vehicle parameters for EV-aware routing

--exclude: optional string

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

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

Body param: Geometry encoding format. Default: geojson.

--mode: optional "auto" or "foot" or "bicycle"

Body param: Travel mode (default: auto)

--overview: optional "full" or "simplified" or "false"

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

--steps: optional boolean

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

--traffic-model: optional "best_guess" or "optimistic" or "pessimistic"

Body param: Traffic prediction model (only used when depart_at is set)

--waypoint: optional array of object { lat, lng }

Body param: Intermediate waypoints to visit in order (maximum 25)

ReturnsExpand Collapse
route_result: 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: object { 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.

Point: array of number

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

LineString or MultiPoint: array of array of number

Array of [lng, lat] positions

Polygon or MultiLineString: 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

"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"
"Feature"

Calculate a route between two points

plaza routing route \
  --api-key 'My API Key' \
  --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"
}