# Optimize ## Optimize route through waypoints `OptimizeResult optimize().create(OptimizeCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())` **post** `/api/v1/optimize` Optimize route through waypoints ### Parameters - `OptimizeCreateParams params` - `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. - `List 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. - `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` - `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` - `FEATURE("Feature")` - `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` - `FEATURE_COLLECTION("FeatureCollection")` - `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` - `PROCESSING("processing")` ### Example ```java 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; import java.util.List; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); OptimizeRequest params = OptimizeRequest.builder() .waypoints(List.of( 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(); 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 `OptimizeJobStatus optimize().retrieve(OptimizeRetrieveParamsparams = OptimizeRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())` **get** `/api/v1/optimize/{job_id}` Get async optimization result ### Parameters - `OptimizeRetrieveParams params` - `Optional jobId` ### 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")` - `Optional result` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `List 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. - `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` - `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` - `FEATURE("Feature")` - `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` - `FEATURE_COLLECTION("FeatureCollection")` ### Example ```java 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; public final class Main { private Main() {} public static void main(String[] args) { PlazaClient client = PlazaOkHttpClient.fromEnv(); 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. - `List 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. - `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` - `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` - `FEATURE("Feature")` - `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` - `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")` - `Optional result` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `List 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. - `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` - `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` - `FEATURE("Feature")` - `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` - `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`. - `String jobId` 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. - `List waypoints` Waypoints to visit in optimized order (2-50 points) - `double lat` Latitude in decimal degrees (-90 to 90) - `double lng` Longitude in decimal degrees (-180 to 180) - `Optional mode` Travel mode (default: `auto`) - `AUTO("auto")` - `FOOT("foot")` - `BICYCLE("bicycle")` - `Optional roundtrip` 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. - `List 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. - `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` - `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` - `FEATURE("Feature")` - `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` - `FEATURE_COLLECTION("FeatureCollection")` - `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` - `PROCESSING("processing")`