API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Optimize

Optimize route through waypoints

optimize.create(**kwargs) -> OptimizeResult

POST/api/v1/optimize

Get async optimization result

optimize.retrieve(job_id) -> OptimizeJobStatus { status, result }

GET/api/v1/optimize/{job_id}

ModelsExpand Collapse

class OptimizeCompletedResult { features, optimization, roundtrip, 2 more }

Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics.

features: Array[{ geometry, properties, type}]

Waypoints in optimized visit order

geometry: GeoJsonGeometry { coordinates, type }

GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]

Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

One of the following:

Array[Float]

[longitude, latitude] or [longitude, latitude, elevation]

Array[Array[Float]]

Array of [lng, lat] positions

Array[Array[Array[Float]]]

Array of linear rings / line strings

Array[Array[Array[Array[Float]]]]

Array of polygons

type: :Point | :LineString | :Polygon | 3 more

Geometry type

One of the following:

:Point

:LineString

:Polygon

:MultiPoint

:MultiLineString

:MultiPolygon

properties: { cost_s, cumulative_cost_s, waypoint_index}

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: Integer

Position of this waypoint in the optimized visit order (0-based)

type: :Feature

optimization: String

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: :FeatureCollection

class OptimizeJobStatus { status, result }

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

One of the following:

:completed

:processing

result: OptimizeCompletedResult { features, optimization, roundtrip, 2 more }

Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics.

features: Array[{ geometry, properties, type}]

Waypoints in optimized visit order

geometry: GeoJsonGeometry { coordinates, type }

GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]

Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

One of the following:

Array[Float]

[longitude, latitude] or [longitude, latitude, elevation]

Array[Array[Float]]

Array of [lng, lat] positions

Array[Array[Array[Float]]]

Array of linear rings / line strings

Array[Array[Array[Array[Float]]]]

Array of polygons

type: :Point | :LineString | :Polygon | 3 more

Geometry type

One of the following:

:Point

:LineString

:Polygon

:MultiPoint

:MultiLineString

:MultiPolygon

properties: { cost_s, cumulative_cost_s, waypoint_index}

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: Integer

Position of this waypoint in the optimized visit order (0-based)

type: :Feature

optimization: String

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: :FeatureCollection

class OptimizeProcessingResult { job_id, status }

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

class OptimizeRequest { waypoints, mode, roundtrip }

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[{ lat, lng}]

Waypoints to visit in optimized order (2-50 points)

lat: Float

Latitude in decimal degrees (-90 to 90)

maximum90

minimum-90

lng: Float

Longitude in decimal degrees (-180 to 180)

maximum180

minimum-180

mode: :auto | :foot | :bicycle

Travel mode (default: auto)

One of the following:

:auto

:foot

:bicycle

roundtrip: bool

Whether the route should return to the starting waypoint (default: true)

OptimizeResult = OptimizeCompletedResult { features, optimization, roundtrip, 2 more } | OptimizeProcessingResult { job_id, status }

Optimization response — either a completed FeatureCollection with the optimized route, or an async job reference to poll.

One of the following:

class OptimizeCompletedResult { features, optimization, roundtrip, 2 more }

Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics.

features: Array[{ geometry, properties, type}]

Waypoints in optimized visit order

geometry: GeoJsonGeometry { coordinates, type }

GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]

Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

One of the following:

Array[Float]

[longitude, latitude] or [longitude, latitude, elevation]

Array[Array[Float]]

Array of [lng, lat] positions

Array[Array[Array[Float]]]

Array of linear rings / line strings

Array[Array[Array[Array[Float]]]]

Array of polygons

type: :Point | :LineString | :Polygon | 3 more

Geometry type

One of the following:

:Point

:LineString

:Polygon

:MultiPoint

:MultiLineString

:MultiPolygon

properties: { cost_s, cumulative_cost_s, waypoint_index}

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: Integer

Position of this waypoint in the optimized visit order (0-based)

type: :Feature

optimization: String

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: :FeatureCollection

class OptimizeProcessingResult { job_id, status }

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