Skip to content
Plaza Plaza Docs
GuidesBlogPlaygroundDashboard
API Reference
Optimize

Optimize route through waypoints

client.optimize.create(OptimizeCreateParams { waypoints, format, mode, roundtrip } params, RequestOptionsoptions?): OptimizeResult
POST/api/v1/optimize

Optimize route through waypoints

ParametersExpand Collapse
params: OptimizeCreateParams { waypoints, format, mode, roundtrip }
waypoints: Array<Waypoint>

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

lat: number

Latitude in decimal degrees (-90 to 90)

maximum90
minimum-90
lng: number

Longitude in decimal degrees (-180 to 180)

maximum180
minimum-180
format?: string

Query param: Response format: json (default), geojson, csv, ndjson

mode?: "auto" | "foot" | "bicycle"

Body param: Travel mode (default: auto)

One of the following:
"auto"
"foot"
"bicycle"
roundtrip?: boolean

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

ReturnsExpand Collapse
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:
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<Feature>

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<number> | Array<Array<number>> | Array<Array<Array<number>>> | Array<Array<Array<Array<number>>>>

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

One of the following:
Array<number>
Array<Array<number>>
Array<Array<Array<number>>>
Array<Array<Array<Array<number>>>>
type: "Point" | "LineString" | "Polygon" | 3 more

Geometry type

One of the following:
"Point"
"LineString"
"Polygon"
"MultiPoint"
"MultiLineString"
"MultiPolygon"
properties: Properties { cost_s, cumulative_cost_s, waypoint_index }
cost_s: number

Travel time in seconds from the previous waypoint to this one (0 for the first waypoint)

cumulative_cost_s: number

Cumulative travel time in seconds from the start to this waypoint

waypoint_index: number

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

type: "Feature"
optimization: string

Optimization method used (e.g. nearest_neighbor, 2opt)

roundtrip: boolean

Whether the route returns to the starting waypoint

total_cost_s: number

Total travel time for the optimized route in seconds

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

Optimize route through waypoints

import Plaza from '@plazafyi/sdk';

const client = new Plaza({
  apiKey: process.env['PLAZA_API_KEY'], // This is the default and can be omitted
});

const optimizeResult = await client.optimize.create({
  waypoints: [
    { lat: 48.8566, lng: 2.3522 },
    { lat: 48.8606, lng: 2.3376 },
    { lat: 48.8584, lng: 2.2945 },
  ],
});

console.log(optimizeResult);
{
  "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
{
  "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"
}