# Optimize ## Optimize route through waypoints `$ plaza optimize create` **post** `/api/v1/optimize` Optimize route through waypoints ### Parameters - `--waypoint: array of object { lat, lng }` Waypoints to visit in optimized order (2-50 points) - `--mode: optional "auto" or "foot" or "bicycle"` Travel mode (default: `auto`) - `--roundtrip: optional boolean` Whether the route should return to the starting waypoint (default: true) ### Returns - `optimize_result: OptimizeCompletedResult or OptimizeProcessingResult` Optimization response — either a completed FeatureCollection with the optimized route, or an async job reference to poll. - `optimize_completed_result: object { features, optimization, roundtrip, 2 more }` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: array of object { geometry, properties, type }` Waypoints in optimized visit order - `geometry: object { coordinates, type }` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Point: array of number` [longitude, latitude] or [longitude, latitude, elevation] - `LineString or MultiPoint: array of array of number` Array of [lng, lat] positions - `Polygon or MultiLineString: array of array of array of number` Array of linear rings / line strings - `MultiPolygon: array of array of array of array of number` Array of polygons - `type: "Point" or "LineString" or "Polygon" or 3 more` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: object { cost_s, cumulative_cost_s, waypoint_index }` - `cost_s: number` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `cumulative_cost_s: number` Cumulative travel time in seconds from the start to this waypoint - `waypoint_index: number` Position of this waypoint in the optimized visit order (0-based) - `type: "Feature"` - `"Feature"` - `optimization: string` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `roundtrip: boolean` Whether the route returns to the starting waypoint - `total_cost_s: number` Total travel time for the optimized route in seconds - `type: "FeatureCollection"` - `"FeatureCollection"` - `optimize_processing_result: object { job_id, status }` Async optimization in progress. Poll `GET /api/v1/optimize/{job_id}` until the status changes to `completed` or `failed`. - `job_id: string` Job ID for polling the result - `status: "processing"` Always `processing` - `"processing"` ### Example ```cli plaza optimize create \ --api-key 'My API Key' \ --waypoint '{lat: 48.8566, lng: 2.3522}' \ --waypoint '{lat: 48.8606, lng: 2.3376}' \ --waypoint '{lat: 48.8584, lng: 2.2945}' ``` #### 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 `$ plaza optimize retrieve` **get** `/api/v1/optimize/{job_id}` Get async optimization result ### Parameters - `--job-id: string` ### Returns - `optimize_job_status: object { status, result }` 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: "completed" or "processing"` Current job state - `"completed"` - `"processing"` - `result: optional object { features, optimization, roundtrip, 2 more }` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: array of object { geometry, properties, type }` Waypoints in optimized visit order - `geometry: object { coordinates, type }` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Point: array of number` [longitude, latitude] or [longitude, latitude, elevation] - `LineString or MultiPoint: array of array of number` Array of [lng, lat] positions - `Polygon or MultiLineString: array of array of array of number` Array of linear rings / line strings - `MultiPolygon: array of array of array of array of number` Array of polygons - `type: "Point" or "LineString" or "Polygon" or 3 more` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: object { cost_s, cumulative_cost_s, waypoint_index }` - `cost_s: number` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `cumulative_cost_s: number` Cumulative travel time in seconds from the start to this waypoint - `waypoint_index: number` Position of this waypoint in the optimized visit order (0-based) - `type: "Feature"` - `"Feature"` - `optimization: string` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `roundtrip: boolean` Whether the route returns to the starting waypoint - `total_cost_s: number` Total travel time for the optimized route in seconds - `type: "FeatureCollection"` - `"FeatureCollection"` ### Example ```cli plaza optimize retrieve \ --api-key 'My API Key' \ --job-id 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 - `optimize_completed_result: object { features, optimization, roundtrip, 2 more }` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: array of object { geometry, properties, type }` Waypoints in optimized visit order - `geometry: object { coordinates, type }` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Point: array of number` [longitude, latitude] or [longitude, latitude, elevation] - `LineString or MultiPoint: array of array of number` Array of [lng, lat] positions - `Polygon or MultiLineString: array of array of array of number` Array of linear rings / line strings - `MultiPolygon: array of array of array of array of number` Array of polygons - `type: "Point" or "LineString" or "Polygon" or 3 more` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: object { cost_s, cumulative_cost_s, waypoint_index }` - `cost_s: number` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `cumulative_cost_s: number` Cumulative travel time in seconds from the start to this waypoint - `waypoint_index: number` Position of this waypoint in the optimized visit order (0-based) - `type: "Feature"` - `"Feature"` - `optimization: string` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `roundtrip: boolean` Whether the route returns to the starting waypoint - `total_cost_s: number` Total travel time for the optimized route in seconds - `type: "FeatureCollection"` - `"FeatureCollection"` ### Optimize Job Status - `optimize_job_status: object { status, result }` 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: "completed" or "processing"` Current job state - `"completed"` - `"processing"` - `result: optional object { features, optimization, roundtrip, 2 more }` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: array of object { geometry, properties, type }` Waypoints in optimized visit order - `geometry: object { coordinates, type }` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Point: array of number` [longitude, latitude] or [longitude, latitude, elevation] - `LineString or MultiPoint: array of array of number` Array of [lng, lat] positions - `Polygon or MultiLineString: array of array of array of number` Array of linear rings / line strings - `MultiPolygon: array of array of array of array of number` Array of polygons - `type: "Point" or "LineString" or "Polygon" or 3 more` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: object { cost_s, cumulative_cost_s, waypoint_index }` - `cost_s: number` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `cumulative_cost_s: number` Cumulative travel time in seconds from the start to this waypoint - `waypoint_index: number` Position of this waypoint in the optimized visit order (0-based) - `type: "Feature"` - `"Feature"` - `optimization: string` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `roundtrip: boolean` Whether the route returns to the starting waypoint - `total_cost_s: number` Total travel time for the optimized route in seconds - `type: "FeatureCollection"` - `"FeatureCollection"` ### Optimize Processing Result - `optimize_processing_result: object { job_id, status }` Async optimization in progress. Poll `GET /api/v1/optimize/{job_id}` until the status changes to `completed` or `failed`. - `job_id: string` Job ID for polling the result - `status: "processing"` Always `processing` - `"processing"` ### Optimize Request - `optimize_request: object { waypoints, mode, roundtrip }` 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: array of object { lat, lng }` Waypoints to visit in optimized order (2-50 points) - `lat: number` Latitude in decimal degrees (-90 to 90) - `lng: number` Longitude in decimal degrees (-180 to 180) - `mode: optional "auto" or "foot" or "bicycle"` Travel mode (default: `auto`) - `"auto"` - `"foot"` - `"bicycle"` - `roundtrip: optional boolean` Whether the route should return to the starting waypoint (default: true) ### Optimize Result - `optimize_result: OptimizeCompletedResult or OptimizeProcessingResult` Optimization response — either a completed FeatureCollection with the optimized route, or an async job reference to poll. - `optimize_completed_result: object { features, optimization, roundtrip, 2 more }` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: array of object { geometry, properties, type }` Waypoints in optimized visit order - `geometry: object { coordinates, type }` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Point: array of number` [longitude, latitude] or [longitude, latitude, elevation] - `LineString or MultiPoint: array of array of number` Array of [lng, lat] positions - `Polygon or MultiLineString: array of array of array of number` Array of linear rings / line strings - `MultiPolygon: array of array of array of array of number` Array of polygons - `type: "Point" or "LineString" or "Polygon" or 3 more` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: object { cost_s, cumulative_cost_s, waypoint_index }` - `cost_s: number` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `cumulative_cost_s: number` Cumulative travel time in seconds from the start to this waypoint - `waypoint_index: number` Position of this waypoint in the optimized visit order (0-based) - `type: "Feature"` - `"Feature"` - `optimization: string` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `roundtrip: boolean` Whether the route returns to the starting waypoint - `total_cost_s: number` Total travel time for the optimized route in seconds - `type: "FeatureCollection"` - `"FeatureCollection"` - `optimize_processing_result: object { job_id, status }` Async optimization in progress. Poll `GET /api/v1/optimize/{job_id}` until the status changes to `completed` or `failed`. - `job_id: string` Job ID for polling the result - `status: "processing"` Always `processing` - `"processing"`