# Optimize ## Optimize route through waypoints `client.Optimize.New(ctx, body) (*OptimizeResult, error)` **post** `/api/v1/optimize` Optimize route through waypoints ### Parameters - `body OptimizeNewParams` - `OptimizeRequest param.Field[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 - `type OptimizeResult interface{…}` Optimization response — either a completed FeatureCollection with the optimized route, or an async job reference to poll. - `type OptimizeCompletedResult struct{…}` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `Features []OptimizeCompletedResultFeature` 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 GeoJsonGeometryCoordinatesUnion` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `type GeoJsonGeometryCoordinatesPoint []float64` [longitude, latitude] or [longitude, latitude, elevation] - `type GeoJsonGeometryCoordinatesLineStringOrMultiPoint [][]float64` Array of [lng, lat] positions - `type GeoJsonGeometryCoordinatesPolygonOrMultiLineString [][][]float64` Array of linear rings / line strings - `type GeoJsonGeometryCoordinatesMultiPolygon [][][][]float64` Array of polygons - `Type GeoJsonGeometryType` Geometry type - `const GeoJsonGeometryTypePoint GeoJsonGeometryType = "Point"` - `const GeoJsonGeometryTypeLineString GeoJsonGeometryType = "LineString"` - `const GeoJsonGeometryTypePolygon GeoJsonGeometryType = "Polygon"` - `const GeoJsonGeometryTypeMultiPoint GeoJsonGeometryType = "MultiPoint"` - `const GeoJsonGeometryTypeMultiLineString GeoJsonGeometryType = "MultiLineString"` - `const GeoJsonGeometryTypeMultiPolygon GeoJsonGeometryType = "MultiPolygon"` - `Properties OptimizeCompletedResultFeaturesProperties` - `CostS float64` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `CumulativeCostS float64` Cumulative travel time in seconds from the start to this waypoint - `WaypointIndex int64` Position of this waypoint in the optimized visit order (0-based) - `Type OptimizeCompletedResultFeaturesType` - `const OptimizeCompletedResultFeaturesTypeFeature OptimizeCompletedResultFeaturesType = "Feature"` - `Optimization string` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `Roundtrip bool` Whether the route returns to the starting waypoint - `TotalCostS float64` Total travel time for the optimized route in seconds - `Type OptimizeCompletedResultType` - `const OptimizeCompletedResultTypeFeatureCollection OptimizeCompletedResultType = "FeatureCollection"` - `type OptimizeProcessingResult struct{…}` 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 OptimizeProcessingResultStatus` Always `processing` - `const OptimizeProcessingResultStatusProcessing OptimizeProcessingResultStatus = "processing"` ### Example ```go package main import ( "context" "fmt" "github.com/plazafyi/plaza-go" "github.com/plazafyi/plaza-go/option" ) func main() { client := githubcomplazafyiplazago.NewClient( option.WithAPIKey("My API Key"), ) optimizeResult, err := client.Optimize.New(context.TODO(), githubcomplazafyiplazago.OptimizeNewParams{ OptimizeRequest: githubcomplazafyiplazago.OptimizeRequestParam{ Waypoints: githubcomplazafyiplazago.F([]githubcomplazafyiplazago.OptimizeRequestWaypointParam{githubcomplazafyiplazago.OptimizeRequestWaypointParam{ Lat: githubcomplazafyiplazago.F(48.856600), Lng: githubcomplazafyiplazago.F(2.352200), }, githubcomplazafyiplazago.OptimizeRequestWaypointParam{ Lat: githubcomplazafyiplazago.F(48.860600), Lng: githubcomplazafyiplazago.F(2.337600), }, githubcomplazafyiplazago.OptimizeRequestWaypointParam{ Lat: githubcomplazafyiplazago.F(48.858400), Lng: githubcomplazafyiplazago.F(2.294500), }}), }, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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.Get(ctx, jobID) (*OptimizeJobStatus, error)` **get** `/api/v1/optimize/{job_id}` Get async optimization result ### Parameters - `jobID string` ### Returns - `type OptimizeJobStatus struct{…}` 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 OptimizeJobStatusStatus` Current job state - `const OptimizeJobStatusStatusCompleted OptimizeJobStatusStatus = "completed"` - `const OptimizeJobStatusStatusProcessing OptimizeJobStatusStatus = "processing"` - `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 []OptimizeCompletedResultFeature` 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 GeoJsonGeometryCoordinatesUnion` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `type GeoJsonGeometryCoordinatesPoint []float64` [longitude, latitude] or [longitude, latitude, elevation] - `type GeoJsonGeometryCoordinatesLineStringOrMultiPoint [][]float64` Array of [lng, lat] positions - `type GeoJsonGeometryCoordinatesPolygonOrMultiLineString [][][]float64` Array of linear rings / line strings - `type GeoJsonGeometryCoordinatesMultiPolygon [][][][]float64` Array of polygons - `Type GeoJsonGeometryType` Geometry type - `const GeoJsonGeometryTypePoint GeoJsonGeometryType = "Point"` - `const GeoJsonGeometryTypeLineString GeoJsonGeometryType = "LineString"` - `const GeoJsonGeometryTypePolygon GeoJsonGeometryType = "Polygon"` - `const GeoJsonGeometryTypeMultiPoint GeoJsonGeometryType = "MultiPoint"` - `const GeoJsonGeometryTypeMultiLineString GeoJsonGeometryType = "MultiLineString"` - `const GeoJsonGeometryTypeMultiPolygon GeoJsonGeometryType = "MultiPolygon"` - `Properties OptimizeCompletedResultFeaturesProperties` - `CostS float64` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `CumulativeCostS float64` Cumulative travel time in seconds from the start to this waypoint - `WaypointIndex int64` Position of this waypoint in the optimized visit order (0-based) - `Type OptimizeCompletedResultFeaturesType` - `const OptimizeCompletedResultFeaturesTypeFeature OptimizeCompletedResultFeaturesType = "Feature"` - `Optimization string` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `Roundtrip bool` Whether the route returns to the starting waypoint - `TotalCostS float64` Total travel time for the optimized route in seconds - `Type OptimizeCompletedResultType` - `const OptimizeCompletedResultTypeFeatureCollection OptimizeCompletedResultType = "FeatureCollection"` ### Example ```go package main import ( "context" "fmt" "github.com/plazafyi/plaza-go" "github.com/plazafyi/plaza-go/option" ) func main() { client := githubcomplazafyiplazago.NewClient( option.WithAPIKey("My API Key"), ) optimizeJobStatus, err := client.Optimize.Get(context.TODO(), "job_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 - `type OptimizeCompletedResult struct{…}` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `Features []OptimizeCompletedResultFeature` 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 GeoJsonGeometryCoordinatesUnion` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `type GeoJsonGeometryCoordinatesPoint []float64` [longitude, latitude] or [longitude, latitude, elevation] - `type GeoJsonGeometryCoordinatesLineStringOrMultiPoint [][]float64` Array of [lng, lat] positions - `type GeoJsonGeometryCoordinatesPolygonOrMultiLineString [][][]float64` Array of linear rings / line strings - `type GeoJsonGeometryCoordinatesMultiPolygon [][][][]float64` Array of polygons - `Type GeoJsonGeometryType` Geometry type - `const GeoJsonGeometryTypePoint GeoJsonGeometryType = "Point"` - `const GeoJsonGeometryTypeLineString GeoJsonGeometryType = "LineString"` - `const GeoJsonGeometryTypePolygon GeoJsonGeometryType = "Polygon"` - `const GeoJsonGeometryTypeMultiPoint GeoJsonGeometryType = "MultiPoint"` - `const GeoJsonGeometryTypeMultiLineString GeoJsonGeometryType = "MultiLineString"` - `const GeoJsonGeometryTypeMultiPolygon GeoJsonGeometryType = "MultiPolygon"` - `Properties OptimizeCompletedResultFeaturesProperties` - `CostS float64` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `CumulativeCostS float64` Cumulative travel time in seconds from the start to this waypoint - `WaypointIndex int64` Position of this waypoint in the optimized visit order (0-based) - `Type OptimizeCompletedResultFeaturesType` - `const OptimizeCompletedResultFeaturesTypeFeature OptimizeCompletedResultFeaturesType = "Feature"` - `Optimization string` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `Roundtrip bool` Whether the route returns to the starting waypoint - `TotalCostS float64` Total travel time for the optimized route in seconds - `Type OptimizeCompletedResultType` - `const OptimizeCompletedResultTypeFeatureCollection OptimizeCompletedResultType = "FeatureCollection"` ### Optimize Job Status - `type OptimizeJobStatus struct{…}` 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 OptimizeJobStatusStatus` Current job state - `const OptimizeJobStatusStatusCompleted OptimizeJobStatusStatus = "completed"` - `const OptimizeJobStatusStatusProcessing OptimizeJobStatusStatus = "processing"` - `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 []OptimizeCompletedResultFeature` 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 GeoJsonGeometryCoordinatesUnion` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `type GeoJsonGeometryCoordinatesPoint []float64` [longitude, latitude] or [longitude, latitude, elevation] - `type GeoJsonGeometryCoordinatesLineStringOrMultiPoint [][]float64` Array of [lng, lat] positions - `type GeoJsonGeometryCoordinatesPolygonOrMultiLineString [][][]float64` Array of linear rings / line strings - `type GeoJsonGeometryCoordinatesMultiPolygon [][][][]float64` Array of polygons - `Type GeoJsonGeometryType` Geometry type - `const GeoJsonGeometryTypePoint GeoJsonGeometryType = "Point"` - `const GeoJsonGeometryTypeLineString GeoJsonGeometryType = "LineString"` - `const GeoJsonGeometryTypePolygon GeoJsonGeometryType = "Polygon"` - `const GeoJsonGeometryTypeMultiPoint GeoJsonGeometryType = "MultiPoint"` - `const GeoJsonGeometryTypeMultiLineString GeoJsonGeometryType = "MultiLineString"` - `const GeoJsonGeometryTypeMultiPolygon GeoJsonGeometryType = "MultiPolygon"` - `Properties OptimizeCompletedResultFeaturesProperties` - `CostS float64` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `CumulativeCostS float64` Cumulative travel time in seconds from the start to this waypoint - `WaypointIndex int64` Position of this waypoint in the optimized visit order (0-based) - `Type OptimizeCompletedResultFeaturesType` - `const OptimizeCompletedResultFeaturesTypeFeature OptimizeCompletedResultFeaturesType = "Feature"` - `Optimization string` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `Roundtrip bool` Whether the route returns to the starting waypoint - `TotalCostS float64` Total travel time for the optimized route in seconds - `Type OptimizeCompletedResultType` - `const OptimizeCompletedResultTypeFeatureCollection OptimizeCompletedResultType = "FeatureCollection"` ### Optimize Processing Result - `type OptimizeProcessingResult struct{…}` 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 OptimizeProcessingResultStatus` Always `processing` - `const OptimizeProcessingResultStatusProcessing OptimizeProcessingResultStatus = "processing"` ### Optimize Request - `type OptimizeRequest struct{…}` 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 []OptimizeRequestWaypoint` Waypoints to visit in optimized order (2-50 points) - `Lat float64` Latitude in decimal degrees (-90 to 90) - `Lng float64` Longitude in decimal degrees (-180 to 180) - `Mode OptimizeRequestMode` Travel mode (default: `auto`) - `const OptimizeRequestModeAuto OptimizeRequestMode = "auto"` - `const OptimizeRequestModeFoot OptimizeRequestMode = "foot"` - `const OptimizeRequestModeBicycle OptimizeRequestMode = "bicycle"` - `Roundtrip bool` Whether the route should return to the starting waypoint (default: true) ### Optimize Result - `type OptimizeResult interface{…}` Optimization response — either a completed FeatureCollection with the optimized route, or an async job reference to poll. - `type OptimizeCompletedResult struct{…}` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `Features []OptimizeCompletedResultFeature` 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 GeoJsonGeometryCoordinatesUnion` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `type GeoJsonGeometryCoordinatesPoint []float64` [longitude, latitude] or [longitude, latitude, elevation] - `type GeoJsonGeometryCoordinatesLineStringOrMultiPoint [][]float64` Array of [lng, lat] positions - `type GeoJsonGeometryCoordinatesPolygonOrMultiLineString [][][]float64` Array of linear rings / line strings - `type GeoJsonGeometryCoordinatesMultiPolygon [][][][]float64` Array of polygons - `Type GeoJsonGeometryType` Geometry type - `const GeoJsonGeometryTypePoint GeoJsonGeometryType = "Point"` - `const GeoJsonGeometryTypeLineString GeoJsonGeometryType = "LineString"` - `const GeoJsonGeometryTypePolygon GeoJsonGeometryType = "Polygon"` - `const GeoJsonGeometryTypeMultiPoint GeoJsonGeometryType = "MultiPoint"` - `const GeoJsonGeometryTypeMultiLineString GeoJsonGeometryType = "MultiLineString"` - `const GeoJsonGeometryTypeMultiPolygon GeoJsonGeometryType = "MultiPolygon"` - `Properties OptimizeCompletedResultFeaturesProperties` - `CostS float64` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `CumulativeCostS float64` Cumulative travel time in seconds from the start to this waypoint - `WaypointIndex int64` Position of this waypoint in the optimized visit order (0-based) - `Type OptimizeCompletedResultFeaturesType` - `const OptimizeCompletedResultFeaturesTypeFeature OptimizeCompletedResultFeaturesType = "Feature"` - `Optimization string` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `Roundtrip bool` Whether the route returns to the starting waypoint - `TotalCostS float64` Total travel time for the optimized route in seconds - `Type OptimizeCompletedResultType` - `const OptimizeCompletedResultTypeFeatureCollection OptimizeCompletedResultType = "FeatureCollection"` - `type OptimizeProcessingResult struct{…}` 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 OptimizeProcessingResultStatus` Always `processing` - `const OptimizeProcessingResultStatusProcessing OptimizeProcessingResultStatus = "processing"`