Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference
Optimize

Optimize route through waypoints

optimize().create(OptimizeCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none()) : OptimizeResult
POST/api/v1/optimize

Optimize route through waypoints

ParametersExpand Collapse
params: OptimizeCreateParams
format: Optional<String>

Response format: json (default), geojson, csv, ndjson

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

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

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: 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
costS: Double

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

cumulativeCostS: Double

Cumulative travel time in seconds from the start to this waypoint

waypointIndex: Long

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

type: Type
optimization: String

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

roundtrip: Boolean

Whether the route returns to the starting waypoint

totalCostS: Double

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.

jobId: String

Job ID for polling the result

status: Status

Always processing

Optimize route through waypoints

package com.plazafyi.example

import com.plazafyi.client.PlazaClient
import com.plazafyi.client.okhttp.PlazaOkHttpClient
import com.plazafyi.models.optimize.OptimizeCreateParams
import com.plazafyi.models.optimize.OptimizeRequest
import com.plazafyi.models.optimize.OptimizeResult

fun main() {
    val client: PlazaClient = PlazaOkHttpClient.fromEnv()

    val params: OptimizeRequest = OptimizeRequest.builder()
        .waypoints(listOf(
          OptimizeRequest.Waypoint.builder()
              .lat(48.8566)
              .lng(2.3522)
              .build(),
          OptimizeRequest.Waypoint.builder()
              .lat(48.8606)
              .lng(2.3376)
              .build(),
          OptimizeRequest.Waypoint.builder()
              .lat(48.8584)
              .lng(2.2945)
              .build(),
        ))
        .build()
    val optimizeResult: OptimizeResult = client.optimize().create(params)
}
{
  "features": [
    {
      "geometry": {
        "coordinates": [
          2.3522,
          48.8566
        ],
        "type": "Point"
      },
      "properties": {
        "cost_s": 0,
        "cumulative_cost_s": 0,
        "waypoint_index": 0
      },
      "type": "Feature"
    }
  ],
  "optimization": "optimization",
  "roundtrip": true,
  "total_cost_s": 0,
  "type": "FeatureCollection"
}
Returns Examples
{
  "features": [
    {
      "geometry": {
        "coordinates": [
          2.3522,
          48.8566
        ],
        "type": "Point"
      },
      "properties": {
        "cost_s": 0,
        "cumulative_cost_s": 0,
        "waypoint_index": 0
      },
      "type": "Feature"
    }
  ],
  "optimization": "optimization",
  "roundtrip": true,
  "total_cost_s": 0,
  "type": "FeatureCollection"
}