Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference
Routing

Calculate a route between two points

routing.route(RoutingRouteParams**kwargs) -> RouteResult
POST/api/v1/route

Calculate a route between two points

ParametersExpand Collapse
destination: Destination

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

lat: float

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: float

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
origin: Origin

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

lat: float

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: float

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
format: Optional[str]

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

alternatives: Optional[int]

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

maximum3
minimum0
annotations: Optional[bool]

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

depart_at: Optional[Union[str, datetime, null]]

Departure time for traffic-aware routing (ISO 8601)

formatdate-time
ev: Optional[Ev]

Electric vehicle parameters for EV-aware routing

battery_capacity_wh: float

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

connector_types: Optional[SequenceNotStr[str]]

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

initial_charge_pct: Optional[float]

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

maximum1
minimum0
min_charge_pct: Optional[float]

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

maximum1
minimum0
min_power_kw: Optional[float]

Minimum charger power in kilowatts

exclude: Optional[str]

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

geometries: Optional[Literal["geojson", "polyline", "polyline6"]]

Geometry encoding format. Default: geojson.

One of the following:
"geojson"
"polyline"
"polyline6"
mode: Optional[Literal["auto", "foot", "bicycle"]]

Travel mode (default: auto)

One of the following:
"auto"
"foot"
"bicycle"
overview: Optional[Literal["full", "simplified", "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[bool]

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

traffic_model: Optional[Literal["best_guess", "optimistic", "pessimistic"]]

Traffic prediction model (only used when depart_at is set)

One of the following:
"best_guess"
"optimistic"
"pessimistic"
waypoints: Optional[Iterable[Waypoint]]

Intermediate waypoints to visit in order (maximum 25)

lat: float

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: float

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
ReturnsExpand Collapse
class RouteResult: …

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

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

coordinates: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]

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

One of the following:
List[float]

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

List[List[float]]

Array of [lng, lat] positions

List[List[List[float]]]

Array of linear rings / line strings

List[List[List[List[float]]]]

Array of polygons

type: Literal["Point", "LineString", "Polygon", 3 more]

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: Properties

Route metadata

distance_m: float

Total route distance in meters

duration_s: float

Estimated travel duration in seconds

annotations: Optional[Dict[str, object]]

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

charge_profile: Optional[List[List[float]]]

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

charging_stops: Optional[List[Dict[str, object]]]

Recommended charging stops along the route (EV routes only)

edges: Optional[List[Dict[str, object]]]

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

energy_used_wh: Optional[float]

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

type: Literal["Feature"]

Calculate a route between two points

import os
from plaza import Plaza

client = Plaza(
    api_key=os.environ.get("PLAZA_API_KEY"),  # This is the default and can be omitted
)
route_result = client.routing.route(
    destination={
        "lat": 48.8584,
        "lng": 2.2945,
    },
    origin={
        "lat": 48.8566,
        "lng": 2.3522,
    },
)
print(route_result.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"
}