# Optimize ## Optimize route through waypoints `optimize().create(OptimizeCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none()) : OptimizeResult` **post** `/api/v1/optimize` Optimize route through waypoints ### Parameters - `params: OptimizeCreateParams` - `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. ### Returns - `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` 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. - `List` - `List>` - `List>>` - `List>>>` - `type: Type` Geometry type - `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` - `FEATURE("Feature")` - `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` - `FEATURE_COLLECTION("FeatureCollection")` - `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` - `PROCESSING("processing")` ### Example ```kotlin 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) } ``` #### Response ```json { "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" } ``` ## Get async optimization result `optimize().retrieve(OptimizeRetrieveParamsparams = OptimizeRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none()) : OptimizeJobStatus` **get** `/api/v1/optimize/{job_id}` Get async optimization result ### Parameters - `params: OptimizeRetrieveParams` - `jobId: Optional` ### Returns - `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 - `COMPLETED("completed")` - `PROCESSING("processing")` - `result: Optional` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: List` 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. - `List` - `List>` - `List>>` - `List>>>` - `type: Type` Geometry type - `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` - `FEATURE("Feature")` - `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` - `FEATURE_COLLECTION("FeatureCollection")` ### Example ```kotlin package com.plazafyi.example import com.plazafyi.client.PlazaClient import com.plazafyi.client.okhttp.PlazaOkHttpClient import com.plazafyi.models.optimize.OptimizeJobStatus import com.plazafyi.models.optimize.OptimizeRetrieveParams fun main() { val client: PlazaClient = PlazaOkHttpClient.fromEnv() val optimizeJobStatus: OptimizeJobStatus = client.optimize().retrieve("job_id") } ``` #### Response ```json { "status": "completed", "result": { "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" } } ``` ## Domain Types ### Optimize Completed Result - `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` 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. - `List` - `List>` - `List>>` - `List>>>` - `type: Type` Geometry type - `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` - `FEATURE("Feature")` - `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` - `FEATURE_COLLECTION("FeatureCollection")` ### Optimize Job Status - `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 - `COMPLETED("completed")` - `PROCESSING("processing")` - `result: Optional` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: List` 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. - `List` - `List>` - `List>>` - `List>>>` - `type: Type` Geometry type - `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` - `FEATURE("Feature")` - `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` - `FEATURE_COLLECTION("FeatureCollection")` ### Optimize Processing Result - `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` - `PROCESSING("processing")` ### Optimize Request - `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` Waypoints to visit in optimized order (2-50 points) - `lat: Double` Latitude in decimal degrees (-90 to 90) - `lng: Double` Longitude in decimal degrees (-180 to 180) - `mode: Optional` Travel mode (default: `auto`) - `AUTO("auto")` - `FOOT("foot")` - `BICYCLE("bicycle")` - `roundtrip: Optional` Whether the route should return to the starting waypoint (default: true) ### Optimize Result - `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` 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. - `List` - `List>` - `List>>` - `List>>>` - `type: Type` Geometry type - `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` - `FEATURE("Feature")` - `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` - `FEATURE_COLLECTION("FeatureCollection")` - `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` - `PROCESSING("processing")`