Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference
Routing

Calculate a route between two points

client.routing.route(RoutingRouteParams { destination, origin, format, 11 more } params, RequestOptionsoptions?): RouteResult { geometry, properties, type }
POST/api/v1/route

Calculate a route between two points

ParametersExpand Collapse
params: RoutingRouteParams { destination, origin, format, 11 more }
destination: Destination

Body param: 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: Origin

Body param: 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
format?: string

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

alternatives?: number

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

maximum3
minimum0
annotations?: boolean

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

depart_at?: string | null

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

formatdate-time
ev?: Ev | null

Body param: Electric vehicle parameters for EV-aware routing

battery_capacity_wh: number

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

connector_types?: Array<string> | null

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

initial_charge_pct?: number

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

maximum1
minimum0
min_charge_pct?: number

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

maximum1
minimum0
min_power_kw?: number | null

Minimum charger power in kilowatts

exclude?: string | null

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

geometries?: "geojson" | "polyline" | "polyline6"

Body param: Geometry encoding format. Default: geojson.

One of the following:
"geojson"
"polyline"
"polyline6"
mode?: "auto" | "foot" | "bicycle"

Body param: Travel mode (default: auto)

One of the following:
"auto"
"foot"
"bicycle"
overview?: "full" | "simplified" | "false"

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

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

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

traffic_model?: "best_guess" | "optimistic" | "pessimistic" | null

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

One of the following:
"best_guess"
"optimistic"
"pessimistic"
waypoints?: Array<Waypoint> | null

Body param: 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 { 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<number> | Array<Array<number>> | Array<Array<Array<number>>> | Array<Array<Array<Array<number>>>>

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

One of the following:
Array<number>
Array<Array<number>>
Array<Array<Array<number>>>
Array<Array<Array<Array<number>>>>
type: "Point" | "LineString" | "Polygon" | 3 more

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: Properties { 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?: Record<string, unknown> | null

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

charge_profile?: Array<Array<number>> | null

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

charging_stops?: Array<Record<string, unknown>> | null

Recommended charging stops along the route (EV routes only)

edges?: Array<Record<string, unknown>> | null

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

energy_used_wh?: number | null

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

type: "Feature"

Calculate a route between two points

import Plaza from '@plazafyi/sdk';

const client = new Plaza({
  apiKey: process.env['PLAZA_API_KEY'], // This is the default and can be omitted
});

const routeResult = await client.routing.route({
  destination: { lat: 48.8584, lng: 2.2945 },
  origin: { lat: 48.8566, lng: 2.3522 },
});

console.log(routeResult.geometry);
{
  "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"
}