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
Snap a coordinate to the nearest road
routing.nearest(RoutingNearestParams**kwargs) -> NearestResult
GET/api/v1/nearest
Snap a coordinate to the nearest road
routing.nearest_post(RoutingNearestPostParams**kwargs) -> NearestResult
POST/api/v1/nearest
Calculate an isochrone from a point
routing.isochrone(RoutingIsochroneParams**kwargs) -> RoutingIsochroneResponse
GET/api/v1/isochrone
Calculate an isochrone from a point
routing.isochrone_post(RoutingIsochronePostParams**kwargs) -> RoutingIsochronePostResponse
POST/api/v1/isochrone
Calculate a distance matrix between points
routing.matrix(RoutingMatrixParams**kwargs) -> MatrixResult
POST/api/v1/matrix
ModelsExpand Collapse
class MatrixRequest: …

Request body for distance matrix calculation. Computes travel durations (and optionally distances) between every origin-destination pair. Maximum 2,500 pairs (origins × destinations), each list capped at 50 coordinates.

destinations: List[Destination]

Array of destination coordinates (max 50)

lat: float

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: float

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
origins: List[Origin]

Array of origin coordinates (max 50)

lat: float

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: float

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
annotations: Optional[str]

Comma-separated list of annotations to include: duration (always included), distance. Example: duration,distance.

fallback_speed: Optional[float]

Fallback speed in km/h for pairs where no route exists. When set, unreachable pairs get estimated values instead of null.

exclusiveMinimum
minimum0
mode: Optional[Literal["auto", "foot", "bicycle"]]

Travel mode (default: auto)

One of the following:
"auto"
"foot"
"bicycle"
Dict[str, object]

Distance matrix result. The exact response shape depends on the routing backend. Contains duration (and optionally distance) data for all origin-destination pairs. Null values indicate unreachable pairs.

class NearestResult: …

GeoJSON Point Feature representing the nearest point on the road network to the input coordinate. Used for snapping GPS coordinates to roads.

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

Snap result metadata

distance_m: Optional[float]

Distance from the input coordinate to the snapped point in meters

edge_id: Optional[int]

ID of the road network edge that was snapped to

edge_length_m: Optional[float]

Length of the matched road edge in meters

highway: Optional[str]

OSM highway tag value (e.g. residential, primary, motorway)

osm_way_id: Optional[int]

OSM way ID of the matched road segment

surface: Optional[str]

OSM surface tag value (e.g. asphalt, gravel, paved)

type: Literal["Feature"]
class RouteRequest: …

Request body for route calculation. Origin and destination are lat/lng coordinate objects. Supports optional waypoints, alternative routes, turn-by-turn steps, and EV routing parameters.

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
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[datetime]

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[List[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[List[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
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"]