Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference

Routing

Calculate a route between two points
RouteResult routing().route(RoutingRouteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
POST/api/v1/route
Snap a coordinate to the nearest road
NearestResult routing().nearest(RoutingNearestParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
GET/api/v1/nearest
Snap a coordinate to the nearest road
NearestResult routing().nearestPost(RoutingNearestPostParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
POST/api/v1/nearest
Calculate an isochrone from a point
RoutingIsochroneResponse routing().isochrone(RoutingIsochroneParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
GET/api/v1/isochrone
Calculate an isochrone from a point
RoutingIsochronePostResponse routing().isochronePost(RoutingIsochronePostParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
POST/api/v1/isochrone
Calculate a distance matrix between points
MatrixResult routing().matrix(RoutingMatrixParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
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.

List<Destination> destinations

Array of destination coordinates (max 50)

double lat

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
double lng

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
List<Origin> origins

Array of origin coordinates (max 50)

double lat

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
double lng

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
Optional<String> annotations

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

Optional<Double> fallbackSpeed

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

exclusiveMinimum
minimum0
Optional<Mode> mode

Travel mode (default: auto)

One of the following:
AUTO("auto")
FOOT("foot")
BICYCLE("bicycle")
class MatrixResult:

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.

GeoJsonGeometry geometry

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

Coordinates coordinates

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

One of the following:
List<double>
List<List<double>>
List<List<List<double>>>
List<List<List<List<double>>>>
Type type

Geometry type

One of the following:
POINT("Point")
LINE_STRING("LineString")
POLYGON("Polygon")
MULTI_POINT("MultiPoint")
MULTI_LINE_STRING("MultiLineString")
MULTI_POLYGON("MultiPolygon")
Properties properties

Snap result metadata

Optional<Double> distanceM

Distance from the input coordinate to the snapped point in meters

Optional<Long> edgeId

ID of the road network edge that was snapped to

Optional<Double> edgeLengthM

Length of the matched road edge in meters

Optional<String> highway

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

Optional<Long> osmWayId

OSM way ID of the matched road segment

Optional<String> surface

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

Type type
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.

double lat

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
double lng

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
Origin origin

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

double lat

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
double lng

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
Optional<Long> alternatives

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

maximum3
minimum0
Optional<Boolean> annotations

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

Optional<LocalDateTime> departAt

Departure time for traffic-aware routing (ISO 8601)

formatdate-time
Optional<Ev> ev

Electric vehicle parameters for EV-aware routing

double batteryCapacityWh

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

Optional<List<String>> connectorTypes

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

Optional<Double> initialChargePct

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

maximum1
minimum0
Optional<Double> minChargePct

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

maximum1
minimum0
Optional<Double> minPowerKw

Minimum charger power in kilowatts

Optional<String> exclude

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

Optional<Geometries> geometries

Geometry encoding format. Default: geojson.

One of the following:
GEOJSON("geojson")
POLYLINE("polyline")
POLYLINE6("polyline6")
Optional<Mode> mode

Travel mode (default: auto)

One of the following:
AUTO("auto")
FOOT("foot")
BICYCLE("bicycle")
Optional<Overview> overview

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

One of the following:
FULL("full")
SIMPLIFIED("simplified")
FALSE("false")
Optional<Boolean> steps

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

Optional<TrafficModel> trafficModel

Traffic prediction model (only used when depart_at is set)

One of the following:
BEST_GUESS("best_guess")
OPTIMISTIC("optimistic")
PESSIMISTIC("pessimistic")
Optional<List<Waypoint>> waypoints

Intermediate waypoints to visit in order (maximum 25)

double lat

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
double lng

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.

GeoJsonGeometry geometry

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

Coordinates coordinates

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

One of the following:
List<double>
List<List<double>>
List<List<List<double>>>
List<List<List<List<double>>>>
Type type

Geometry type

One of the following:
POINT("Point")
LINE_STRING("LineString")
POLYGON("Polygon")
MULTI_POINT("MultiPoint")
MULTI_LINE_STRING("MultiLineString")
MULTI_POLYGON("MultiPolygon")
Properties properties

Route metadata

double distanceM

Total route distance in meters

double durationS

Estimated travel duration in seconds

Optional<Annotations> annotations

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

Optional<List<List<Double>>> chargeProfile

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

Optional<List<ChargingStop>> chargingStops

Recommended charging stops along the route (EV routes only)

Optional<List<Edge>> edges

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

Optional<Double> energyUsedWh

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

Type type