Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference

Optimize

Optimize route through waypoints
optimize.create(OptimizeCreateParams**kwargs) -> OptimizeResult
POST/api/v1/optimize
Get async optimization result
optimize.retrieve(strjob_id) -> OptimizeJobStatus
GET/api/v1/optimize/{job_id}
ModelsExpand Collapse
class OptimizeCompletedResult: …

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

features: List[Feature]

Waypoints in optimized visit order

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: FeatureProperties
cost_s: float

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

cumulative_cost_s: float

Cumulative travel time in seconds from the start to this waypoint

waypoint_index: int

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

type: Literal["Feature"]
optimization: str

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

roundtrip: bool

Whether the route returns to the starting waypoint

total_cost_s: float

Total travel time for the optimized route in seconds

type: Literal["FeatureCollection"]
class OptimizeJobStatus: …

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: Literal["completed", "processing"]

Current job state

One of the following:
"completed"
"processing"
result: Optional[OptimizeCompletedResult]

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

features: List[Feature]

Waypoints in optimized visit order

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: FeatureProperties
cost_s: float

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

cumulative_cost_s: float

Cumulative travel time in seconds from the start to this waypoint

waypoint_index: int

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

type: Literal["Feature"]
optimization: str

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

roundtrip: bool

Whether the route returns to the starting waypoint

total_cost_s: float

Total travel time for the optimized route in seconds

type: Literal["FeatureCollection"]
class OptimizeProcessingResult: …

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

job_id: str

Job ID for polling the result

status: Literal["processing"]

Always processing

class OptimizeRequest: …

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: List[Waypoint]

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

lat: float

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: float

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
mode: Optional[Literal["auto", "foot", "bicycle"]]

Travel mode (default: auto)

One of the following:
"auto"
"foot"
"bicycle"
roundtrip: Optional[bool]

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

OptimizeResult

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

One of the following:
class OptimizeCompletedResult: …

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

features: List[Feature]

Waypoints in optimized visit order

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: FeatureProperties
cost_s: float

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

cumulative_cost_s: float

Cumulative travel time in seconds from the start to this waypoint

waypoint_index: int

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

type: Literal["Feature"]
optimization: str

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

roundtrip: bool

Whether the route returns to the starting waypoint

total_cost_s: float

Total travel time for the optimized route in seconds

type: Literal["FeatureCollection"]
class OptimizeProcessingResult: …

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

job_id: str

Job ID for polling the result

status: Literal["processing"]

Always processing