Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference

Optimize

Optimize route through waypoints
OptimizeResult optimize().create(OptimizeCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
POST/api/v1/optimize
Get async optimization result
OptimizeJobStatus optimize().retrieve(OptimizeRetrieveParamsparams = OptimizeRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())
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.

List<Feature> features

Waypoints in optimized visit order

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
double costS

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

double cumulativeCostS

Cumulative travel time in seconds from the start to this waypoint

long waypointIndex

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

Type type
String optimization

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

boolean roundtrip

Whether the route returns to the starting waypoint

double totalCostS

Total travel time for the optimized route in seconds

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

Current job state

One of the following:
COMPLETED("completed")
PROCESSING("processing")
Optional<OptimizeCompletedResult> result

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

List<Feature> features

Waypoints in optimized visit order

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
double costS

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

double cumulativeCostS

Cumulative travel time in seconds from the start to this waypoint

long waypointIndex

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

Type type
String optimization

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

boolean roundtrip

Whether the route returns to the starting waypoint

double totalCostS

Total travel time for the optimized route in seconds

Type type
class OptimizeProcessingResult:

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

String jobId

Job ID for polling the result

Status status

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.

List<Waypoint> waypoints

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

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<Mode> mode

Travel mode (default: auto)

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

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

class OptimizeResult: A class that can be one of several variants.union

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

class OptimizeCompletedResult:

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

List<Feature> features

Waypoints in optimized visit order

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
double costS

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

double cumulativeCostS

Cumulative travel time in seconds from the start to this waypoint

long waypointIndex

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

Type type
String optimization

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

boolean roundtrip

Whether the route returns to the starting waypoint

double totalCostS

Total travel time for the optimized route in seconds

Type type
class OptimizeProcessingResult:

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

String jobId

Job ID for polling the result

Status status

Always processing