# Optimize ## Optimize route through waypoints `client.optimize.create(OptimizeCreateParamsbody, RequestOptionsoptions?): OptimizeResult` **post** `/api/v1/optimize` Optimize route through waypoints ### Parameters - `body: OptimizeCreateParams` - `waypoints: Array` 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?: "auto" | "foot" | "bicycle"` Travel mode (default: `auto`) - `"auto"` - `"foot"` - `"bicycle"` - `roundtrip?: boolean` Whether the route should return to the starting waypoint (default: true) ### Returns - `OptimizeResult = OptimizeCompletedResult | OptimizeProcessingResult` Optimization response — either a completed FeatureCollection with the optimized route, or an async job reference to poll. - `OptimizeCompletedResult` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: Array` 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: Array | Array> | Array>> | Array>>>` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array` - `Array>` - `Array>>` - `Array>>>` - `type: "Point" | "LineString" | "Polygon" | 3 more` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: Properties` - `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"` - `OptimizeProcessingResult` 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 ```typescript import Plaza from '@plazafyi/sdk'; const client = new Plaza({ apiKey: process.env['PLAZA_API_KEY'], // This is the default and can be omitted }); const optimizeResult = await client.optimize.create({ waypoints: [ { lat: 48.8566, lng: 2.3522 }, { lat: 48.8606, lng: 2.3376 }, { lat: 48.8584, lng: 2.2945 }, ], }); console.log(optimizeResult); ``` #### 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 `client.optimize.retrieve(stringjobID, RequestOptionsoptions?): OptimizeJobStatus` **get** `/api/v1/optimize/{job_id}` Get async optimization result ### Parameters - `jobID: string` ### Returns - `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: "completed" | "processing"` Current job state - `"completed"` - `"processing"` - `result?: OptimizeCompletedResult | null` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: Array` 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: Array | Array> | Array>> | Array>>>` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array` - `Array>` - `Array>>` - `Array>>>` - `type: "Point" | "LineString" | "Polygon" | 3 more` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: Properties` - `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 ```typescript import Plaza from '@plazafyi/sdk'; const client = new Plaza({ apiKey: process.env['PLAZA_API_KEY'], // This is the default and can be omitted }); const optimizeJobStatus = await client.optimize.retrieve('job_id'); console.log(optimizeJobStatus.status); ``` #### 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 - `OptimizeCompletedResult` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: Array` 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: Array | Array> | Array>> | Array>>>` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array` - `Array>` - `Array>>` - `Array>>>` - `type: "Point" | "LineString" | "Polygon" | 3 more` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: Properties` - `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 - `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: "completed" | "processing"` Current job state - `"completed"` - `"processing"` - `result?: OptimizeCompletedResult | null` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: Array` 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: Array | Array> | Array>> | Array>>>` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array` - `Array>` - `Array>>` - `Array>>>` - `type: "Point" | "LineString" | "Polygon" | 3 more` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: Properties` - `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 - `OptimizeProcessingResult` 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 - `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: Array` 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?: "auto" | "foot" | "bicycle"` Travel mode (default: `auto`) - `"auto"` - `"foot"` - `"bicycle"` - `roundtrip?: boolean` Whether the route should return to the starting waypoint (default: true) ### Optimize Result - `OptimizeResult = OptimizeCompletedResult | OptimizeProcessingResult` Optimization response — either a completed FeatureCollection with the optimized route, or an async job reference to poll. - `OptimizeCompletedResult` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: Array` 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: Array | Array> | Array>> | Array>>>` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `Array` - `Array>` - `Array>>` - `Array>>>` - `type: "Point" | "LineString" | "Polygon" | 3 more` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: Properties` - `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"` - `OptimizeProcessingResult` 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"`