API Reference

Optimize

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Get async optimization result

optimize.retrieve(strjob_id) -> OptimizeJobStatus

GET/api/v1/optimize/{job_id}

Get async optimization result

ParametersExpand Collapse

job_id: str

ReturnsExpand Collapse

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

One of the following:

"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.

One of the following:

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

One of the following:

"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"]

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"]

Get async optimization result

Python

HTTP

TypeScript

Python

Java

Kotlin

Go

Ruby

CLI Tool

PHP

C#

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)

200 example

{
  "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"
  }
}

Returns Examples

200 example

{
  "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"
  }
}