Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference

Routing

Calculate a route between two points
$ plaza routing route
POST/api/v1/route
Snap a coordinate to the nearest road
$ plaza routing nearest
GET/api/v1/nearest
Snap a coordinate to the nearest road
$ plaza routing nearest-post
POST/api/v1/nearest
Calculate an isochrone from a point
$ plaza routing isochrone
GET/api/v1/isochrone
Calculate an isochrone from a point
$ plaza routing isochrone-post
POST/api/v1/isochrone
Calculate a distance matrix between points
$ plaza routing matrix
POST/api/v1/matrix
ModelsExpand Collapse
matrix_request: object { destinations, origins, annotations, 2 more }

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: array of object { lat, lng }

Array of destination coordinates (max 50)

lat: number

Latitude in decimal degrees (-90 to 90)

lng: number

Longitude in decimal degrees (-180 to 180)

origins: array of object { lat, lng }

Array of origin coordinates (max 50)

lat: number

Latitude in decimal degrees (-90 to 90)

lng: number

Longitude in decimal degrees (-180 to 180)

annotations: optional string

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

fallback_speed: optional number

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

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

Travel mode (default: auto)

"auto"
"foot"
"bicycle"
matrix_result: map[unknown]

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.

nearest_result: object { geometry, properties, type }

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

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, edge_id, edge_length_m, 3 more }

Snap result metadata

distance_m: optional number

Distance from the input coordinate to the snapped point in meters

edge_id: optional number

ID of the road network edge that was snapped to

edge_length_m: optional number

Length of the matched road edge in meters

highway: optional string

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

osm_way_id: optional number

OSM way ID of the matched road segment

surface: optional string

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

type: "Feature"
"Feature"
route_request: object { destination, origin, alternatives, 10 more }

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: object { lat, lng }

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

lat: number

Latitude in decimal degrees (-90 to 90)

lng: number

Longitude in decimal degrees (-180 to 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)

lng: number

Longitude in decimal degrees (-180 to 180)

alternatives: optional number

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

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)

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)

min_charge_pct: optional number

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

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.

"geojson"
"polyline"
"polyline6"
mode: optional "auto" or "foot" or "bicycle"

Travel mode (default: auto)

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

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

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

lng: number

Longitude in decimal degrees (-180 to 180)

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"