# Optimize ## Optimize route through waypoints `optimize.create(OptimizeCreateParams**kwargs) -> OptimizeResult` **post** `/api/v1/optimize` Optimize route through waypoints ### Parameters - `waypoints: Iterable[Waypoint]` Waypoints to visit in optimized order (2-50 points) - `lat: float` Latitude in decimal degrees (-90 to 90) - `lng: float` Longitude in decimal degrees (-180 to 180) - `mode: Optional[Literal["auto", "foot", "bicycle"]]` Travel mode (default: `auto`) - `"auto"` - `"foot"` - `"bicycle"` - `roundtrip: Optional[bool]` Whether the route should return to the starting waypoint (default: true) ### Returns - `OptimizeResult` 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. - `features: List[Feature]` 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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List[float]` [longitude, latitude] or [longitude, latitude, elevation] - `List[List[float]]` Array of [lng, lat] positions - `List[List[List[float]]]` Array of linear rings / line strings - `List[List[List[List[float]]]]` Array of polygons - `type: Literal["Point", "LineString", "Polygon", 3 more]` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: FeatureProperties` - `cost_s: float` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `cumulative_cost_s: float` Cumulative travel time in seconds from the start to this waypoint - `waypoint_index: int` Position of this waypoint in the optimized visit order (0-based) - `type: Literal["Feature"]` - `"Feature"` - `optimization: str` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `roundtrip: bool` Whether the route returns to the starting waypoint - `total_cost_s: float` Total travel time for the optimized route in seconds - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` - `class OptimizeProcessingResult: …` Async optimization in progress. Poll `GET /api/v1/optimize/{job_id}` until the status changes to `completed` or `failed`. - `job_id: str` Job ID for polling the result - `status: Literal["processing"]` Always `processing` - `"processing"` ### Example ```python import os from plaza import Plaza client = Plaza( api_key=os.environ.get("PLAZA_API_KEY"), # This is the default and can be omitted ) optimize_result = client.optimize.create( waypoints=[{ "lat": 48.8566, "lng": 2.3522, }, { "lat": 48.8606, "lng": 2.3376, }, { "lat": 48.8584, "lng": 2.2945, }], ) print(optimize_result) ``` #### 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 `optimize.retrieve(strjob_id) -> OptimizeJobStatus` **get** `/api/v1/optimize/{job_id}` Get async optimization result ### Parameters - `job_id: str` ### 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: Literal["completed", "processing"]` Current job state - `"completed"` - `"processing"` - `result: Optional[OptimizeCompletedResult]` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: List[Feature]` 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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List[float]` [longitude, latitude] or [longitude, latitude, elevation] - `List[List[float]]` Array of [lng, lat] positions - `List[List[List[float]]]` Array of linear rings / line strings - `List[List[List[List[float]]]]` Array of polygons - `type: Literal["Point", "LineString", "Polygon", 3 more]` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: FeatureProperties` - `cost_s: float` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `cumulative_cost_s: float` Cumulative travel time in seconds from the start to this waypoint - `waypoint_index: int` Position of this waypoint in the optimized visit order (0-based) - `type: Literal["Feature"]` - `"Feature"` - `optimization: str` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `roundtrip: bool` Whether the route returns to the starting waypoint - `total_cost_s: float` Total travel time for the optimized route in seconds - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` ### Example ```python import os from plaza import Plaza client = Plaza( api_key=os.environ.get("PLAZA_API_KEY"), # This is the default and can be omitted ) optimize_job_status = client.optimize.retrieve( "job_id", ) print(optimize_job_status.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 - `class OptimizeCompletedResult: …` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: List[Feature]` 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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List[float]` [longitude, latitude] or [longitude, latitude, elevation] - `List[List[float]]` Array of [lng, lat] positions - `List[List[List[float]]]` Array of linear rings / line strings - `List[List[List[List[float]]]]` Array of polygons - `type: Literal["Point", "LineString", "Polygon", 3 more]` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: FeatureProperties` - `cost_s: float` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `cumulative_cost_s: float` Cumulative travel time in seconds from the start to this waypoint - `waypoint_index: int` Position of this waypoint in the optimized visit order (0-based) - `type: Literal["Feature"]` - `"Feature"` - `optimization: str` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `roundtrip: bool` Whether the route returns to the starting waypoint - `total_cost_s: float` Total travel time for the optimized route in seconds - `type: Literal["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. - `status: Literal["completed", "processing"]` Current job state - `"completed"` - `"processing"` - `result: Optional[OptimizeCompletedResult]` Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics. - `features: List[Feature]` 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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List[float]` [longitude, latitude] or [longitude, latitude, elevation] - `List[List[float]]` Array of [lng, lat] positions - `List[List[List[float]]]` Array of linear rings / line strings - `List[List[List[List[float]]]]` Array of polygons - `type: Literal["Point", "LineString", "Polygon", 3 more]` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: FeatureProperties` - `cost_s: float` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `cumulative_cost_s: float` Cumulative travel time in seconds from the start to this waypoint - `waypoint_index: int` Position of this waypoint in the optimized visit order (0-based) - `type: Literal["Feature"]` - `"Feature"` - `optimization: str` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `roundtrip: bool` Whether the route returns to the starting waypoint - `total_cost_s: float` Total travel time for the optimized route in seconds - `type: Literal["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`. - `job_id: str` Job ID for polling the result - `status: Literal["processing"]` Always `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. - `waypoints: List[Waypoint]` Waypoints to visit in optimized order (2-50 points) - `lat: float` Latitude in decimal degrees (-90 to 90) - `lng: float` Longitude in decimal degrees (-180 to 180) - `mode: Optional[Literal["auto", "foot", "bicycle"]]` Travel mode (default: `auto`) - `"auto"` - `"foot"` - `"bicycle"` - `roundtrip: Optional[bool]` Whether the route should return to the starting waypoint (default: true) ### Optimize Result - `OptimizeResult` 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. - `features: List[Feature]` 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: Union[List[float], List[List[float]], List[List[List[float]]], List[List[List[List[float]]]]]` Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc. - `List[float]` [longitude, latitude] or [longitude, latitude, elevation] - `List[List[float]]` Array of [lng, lat] positions - `List[List[List[float]]]` Array of linear rings / line strings - `List[List[List[List[float]]]]` Array of polygons - `type: Literal["Point", "LineString", "Polygon", 3 more]` Geometry type - `"Point"` - `"LineString"` - `"Polygon"` - `"MultiPoint"` - `"MultiLineString"` - `"MultiPolygon"` - `properties: FeatureProperties` - `cost_s: float` Travel time in seconds from the previous waypoint to this one (0 for the first waypoint) - `cumulative_cost_s: float` Cumulative travel time in seconds from the start to this waypoint - `waypoint_index: int` Position of this waypoint in the optimized visit order (0-based) - `type: Literal["Feature"]` - `"Feature"` - `optimization: str` Optimization method used (e.g. `nearest_neighbor`, `2opt`) - `roundtrip: bool` Whether the route returns to the starting waypoint - `total_cost_s: float` Total travel time for the optimized route in seconds - `type: Literal["FeatureCollection"]` - `"FeatureCollection"` - `class OptimizeProcessingResult: …` Async optimization in progress. Poll `GET /api/v1/optimize/{job_id}` until the status changes to `completed` or `failed`. - `job_id: str` Job ID for polling the result - `status: Literal["processing"]` Always `processing` - `"processing"`