Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference

Optimize

Optimize route through waypoints
POST/api/v1/optimize
Get async optimization result
GET/api/v1/optimize/{job_id}
ModelsExpand Collapse
OptimizeCompletedResult = object { features, optimization, roundtrip, 2 more }

Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics.

features: array of object { geometry, properties, type }

Waypoints in optimized visit order

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

One of the following:
Point = array of number

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

LineStringOrMultiPoint = array of array of number

Array of [lng, lat] positions

PolygonOrMultiLineString = 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

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: object { cost_s, cumulative_cost_s, waypoint_index }
cost_s: number

Travel time in seconds from the previous waypoint to this one (0 for the first waypoint)

cumulative_cost_s: number

Cumulative travel time in seconds from the start to this waypoint

waypoint_index: number

Position of this waypoint in the optimized visit order (0-based)

type: "Feature"
optimization: string

Optimization method used (e.g. nearest_neighbor, 2opt)

roundtrip: boolean

Whether the route returns to the starting waypoint

total_cost_s: number

Total travel time for the optimized route in seconds

type: "FeatureCollection"
OptimizeJobStatus = object { status, result }

Status of an async optimization job. When completed, the result field contains the full OptimizeCompletedResult. When processing, the job is still running — poll again. Failed jobs return a standard Error response (HTTP 422), not this schema.

status: "completed" or "processing"

Current job state

One of the following:
"completed"
"processing"
result: optional OptimizeCompletedResult { features, optimization, roundtrip, 2 more }

Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics.

features: array of object { geometry, properties, type }

Waypoints in optimized visit order

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

One of the following:
Point = array of number

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

LineStringOrMultiPoint = array of array of number

Array of [lng, lat] positions

PolygonOrMultiLineString = 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

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: object { cost_s, cumulative_cost_s, waypoint_index }
cost_s: number

Travel time in seconds from the previous waypoint to this one (0 for the first waypoint)

cumulative_cost_s: number

Cumulative travel time in seconds from the start to this waypoint

waypoint_index: number

Position of this waypoint in the optimized visit order (0-based)

type: "Feature"
optimization: string

Optimization method used (e.g. nearest_neighbor, 2opt)

roundtrip: boolean

Whether the route returns to the starting waypoint

total_cost_s: number

Total travel time for the optimized route in seconds

type: "FeatureCollection"
OptimizeProcessingResult = object { job_id, status }

Async optimization in progress. Poll GET /api/v1/optimize/{job_id} until the status changes to completed or failed.

job_id: string

Job ID for polling the result

status: "processing"

Always processing

OptimizeRequest = object { waypoints, mode, roundtrip }

Route optimization (Travelling Salesman) request. Finds the most efficient order to visit a set of waypoints. Minimum 2 waypoints, maximum 50. For large inputs, the request may be processed asynchronously.

waypoints: array of object { lat, lng }

Waypoints to visit in optimized order (2-50 points)

lat: number

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: number

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
mode: optional "auto" or "foot" or "bicycle"

Travel mode (default: auto)

One of the following:
"auto"
"foot"
"bicycle"
roundtrip: optional boolean

Whether the route should return to the starting waypoint (default: true)

OptimizeResult = OptimizeCompletedResult { features, optimization, roundtrip, 2 more } or OptimizeProcessingResult { job_id, status }

Optimization response — either a completed FeatureCollection with the optimized route, or an async job reference to poll.

One of the following:
OptimizeCompletedResult = object { features, optimization, roundtrip, 2 more }

Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics.

features: array of object { geometry, properties, type }

Waypoints in optimized visit order

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

One of the following:
Point = array of number

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

LineStringOrMultiPoint = array of array of number

Array of [lng, lat] positions

PolygonOrMultiLineString = 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

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: object { cost_s, cumulative_cost_s, waypoint_index }
cost_s: number

Travel time in seconds from the previous waypoint to this one (0 for the first waypoint)

cumulative_cost_s: number

Cumulative travel time in seconds from the start to this waypoint

waypoint_index: number

Position of this waypoint in the optimized visit order (0-based)

type: "Feature"
optimization: string

Optimization method used (e.g. nearest_neighbor, 2opt)

roundtrip: boolean

Whether the route returns to the starting waypoint

total_cost_s: number

Total travel time for the optimized route in seconds

type: "FeatureCollection"
OptimizeProcessingResult = object { job_id, status }

Async optimization in progress. Poll GET /api/v1/optimize/{job_id} until the status changes to completed or failed.

job_id: string

Job ID for polling the result

status: "processing"

Always processing