# Optimize ## Optimize route through waypoints `OptimizeResult Optimize.Create(OptimizeCreateParamsparameters, CancellationTokencancellationToken = default)` **post** `/api/v1/optimize` Optimize route through waypoints ### Parameters - `OptimizeCreateParams parameters` - `required IReadOnlyList waypoints` Waypoints to visit in optimized order (2-50 points) - `required Double Lat` Latitude in decimal degrees (-90 to 90) - `required Double Lng` Longitude in decimal degrees (-180 to 180) - `Mode mode` Travel mode (default: `auto`) - `"auto"Auto` - `"foot"Foot` - `"bicycle"Bicycle` - `Boolean roundtrip` Whether the route should return to the starting waypoint (default: true) ### 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. - `required IReadOnlyList Features` Waypoints in optimized visit order - `required GeoJsonGeometry Geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `required Coordinates Coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `IReadOnlyList` - `IReadOnlyList>` - `IReadOnlyList>>` - `IReadOnlyList>>>` - `required Type Type` Geometry type - `"Point"Point` - `"LineString"LineString` - `"Polygon"Polygon` - `"MultiPoint"MultiPoint` - `"MultiLineString"MultiLineString` - `"MultiPolygon"MultiPolygon` - `required Properties Properties` - `required Double CostS` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `required Double CumulativeCostS` Cumulative travel time in seconds from the start to this waypoint - `required Long WaypointIndex` Position of this waypoint in the optimized visit order (0-based) - `required Type Type` - `"Feature"Feature` - `required string Optimization` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `required Boolean Roundtrip` Whether the route returns to the starting waypoint - `required Double TotalCostS` Total travel time for the optimized route in seconds - `required Type Type` - `"FeatureCollection"FeatureCollection` - `class OptimizeProcessingResult:` Async optimization in progress. Poll `GET /api/v1/optimize/{job_id}` until the status changes to `completed` or `failed`. - `required string JobID` Job ID for polling the result - `required Status Status` Always `processing` - `"processing"Processing` ### Example ```csharp OptimizeCreateParams parameters = new() { Waypoints = [ new() { Lat = 48.8566, Lng = 2.3522, }, new() { Lat = 48.8606, Lng = 2.3376, }, new() { Lat = 48.8584, Lng = 2.2945, }, ], }; var optimizeResult = await client.Optimize.Create(parameters); Console.WriteLine(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 `OptimizeJobStatus Optimize.Retrieve(OptimizeRetrieveParamsparameters, CancellationTokencancellationToken = default)` **get** `/api/v1/optimize/{job_id}` Get async optimization result ### Parameters - `OptimizeRetrieveParams parameters` - `required string 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. - `required Status Status` Current job state - `"completed"Completed` - `"processing"Processing` - `OptimizeCompletedResult? Result` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `required IReadOnlyList Features` Waypoints in optimized visit order - `required GeoJsonGeometry Geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `required Coordinates Coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `IReadOnlyList` - `IReadOnlyList>` - `IReadOnlyList>>` - `IReadOnlyList>>>` - `required Type Type` Geometry type - `"Point"Point` - `"LineString"LineString` - `"Polygon"Polygon` - `"MultiPoint"MultiPoint` - `"MultiLineString"MultiLineString` - `"MultiPolygon"MultiPolygon` - `required Properties Properties` - `required Double CostS` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `required Double CumulativeCostS` Cumulative travel time in seconds from the start to this waypoint - `required Long WaypointIndex` Position of this waypoint in the optimized visit order (0-based) - `required Type Type` - `"Feature"Feature` - `required string Optimization` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `required Boolean Roundtrip` Whether the route returns to the starting waypoint - `required Double TotalCostS` Total travel time for the optimized route in seconds - `required Type Type` - `"FeatureCollection"FeatureCollection` ### Example ```csharp OptimizeRetrieveParams parameters = new() { JobID = "job_id" }; var optimizeJobStatus = await client.Optimize.Retrieve(parameters); Console.WriteLine(optimizeJobStatus); ``` #### 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. - `required IReadOnlyList Features` Waypoints in optimized visit order - `required GeoJsonGeometry Geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `required Coordinates Coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `IReadOnlyList` - `IReadOnlyList>` - `IReadOnlyList>>` - `IReadOnlyList>>>` - `required Type Type` Geometry type - `"Point"Point` - `"LineString"LineString` - `"Polygon"Polygon` - `"MultiPoint"MultiPoint` - `"MultiLineString"MultiLineString` - `"MultiPolygon"MultiPolygon` - `required Properties Properties` - `required Double CostS` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `required Double CumulativeCostS` Cumulative travel time in seconds from the start to this waypoint - `required Long WaypointIndex` Position of this waypoint in the optimized visit order (0-based) - `required Type Type` - `"Feature"Feature` - `required string Optimization` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `required Boolean Roundtrip` Whether the route returns to the starting waypoint - `required Double TotalCostS` Total travel time for the optimized route in seconds - `required Type Type` - `"FeatureCollection"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. - `required Status Status` Current job state - `"completed"Completed` - `"processing"Processing` - `OptimizeCompletedResult? Result` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `required IReadOnlyList Features` Waypoints in optimized visit order - `required GeoJsonGeometry Geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `required Coordinates Coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `IReadOnlyList` - `IReadOnlyList>` - `IReadOnlyList>>` - `IReadOnlyList>>>` - `required Type Type` Geometry type - `"Point"Point` - `"LineString"LineString` - `"Polygon"Polygon` - `"MultiPoint"MultiPoint` - `"MultiLineString"MultiLineString` - `"MultiPolygon"MultiPolygon` - `required Properties Properties` - `required Double CostS` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `required Double CumulativeCostS` Cumulative travel time in seconds from the start to this waypoint - `required Long WaypointIndex` Position of this waypoint in the optimized visit order (0-based) - `required Type Type` - `"Feature"Feature` - `required string Optimization` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `required Boolean Roundtrip` Whether the route returns to the starting waypoint - `required Double TotalCostS` Total travel time for the optimized route in seconds - `required Type Type` - `"FeatureCollection"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`. - `required string JobID` Job ID for polling the result - `required 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. - `required IReadOnlyList Waypoints` Waypoints to visit in optimized order (2-50 points) - `required Double Lat` Latitude in decimal degrees (-90 to 90) - `required Double Lng` Longitude in decimal degrees (-180 to 180) - `Mode Mode` Travel mode (default: `auto`) - `"auto"Auto` - `"foot"Foot` - `"bicycle"Bicycle` - `Boolean 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. - `required IReadOnlyList Features` Waypoints in optimized visit order - `required GeoJsonGeometry Geometry` GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints. - `required Coordinates Coordinates` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `IReadOnlyList` - `IReadOnlyList>` - `IReadOnlyList>>` - `IReadOnlyList>>>` - `required Type Type` Geometry type - `"Point"Point` - `"LineString"LineString` - `"Polygon"Polygon` - `"MultiPoint"MultiPoint` - `"MultiLineString"MultiLineString` - `"MultiPolygon"MultiPolygon` - `required Properties Properties` - `required Double CostS` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `required Double CumulativeCostS` Cumulative travel time in seconds from the start to this waypoint - `required Long WaypointIndex` Position of this waypoint in the optimized visit order (0-based) - `required Type Type` - `"Feature"Feature` - `required string Optimization` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `required Boolean Roundtrip` Whether the route returns to the starting waypoint - `required Double TotalCostS` Total travel time for the optimized route in seconds - `required Type Type` - `"FeatureCollection"FeatureCollection` - `class OptimizeProcessingResult:` Async optimization in progress. Poll `GET /api/v1/optimize/{job_id}` until the status changes to `completed` or `failed`. - `required string JobID` Job ID for polling the result - `required Status Status` Always `processing` - `"processing"Processing`