Route optimization

Route optimization takes your stops and returns the visit order that minimizes total travel time (the traveling salesman problem).

Route optimization is a premium endpoint — each request counts as 4x.

Small jobs (10 stops or fewer)

10 stops or fewer return synchronously:

curl -X POST https://plaza.fyi/api/v1/optimize \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "waypoints": [
      { "type": "Point", "coordinates": [-73.9857, 40.7484] },
      { "type": "Point", "coordinates": [-74.0060, 40.7128] },
      { "type": "Point", "coordinates": [-73.9712, 40.7831] },
      { "type": "Point", "coordinates": [-73.9680, 40.7614] },
      { "type": "Point", "coordinates": [-73.9855, 40.7580] }
    ],
    "mode": "auto"
  }'

import Plaza from "@plazafyi/sdk";

const client = new Plaza();

const result = await client.v1.optimize({
  locations: [
    { type: "Point", coordinates: [-73.9857, 40.7484] },
    { type: "Point", coordinates: [-74.006, 40.7128] },
    { type: "Point", coordinates: [-73.9712, 40.7831] },
    { type: "Point", coordinates: [-73.968, 40.7614] },
    { type: "Point", coordinates: [-73.9855, 40.758] },
  ],
  mode: "auto",
});

console.log(result.total_cost_s);

import plaza

client = plaza.Client()

result = client.v1.optimize(
    locations=[
        {"type": "Point", "coordinates": [-73.9857, 40.7484]},
        {"type": "Point", "coordinates": [-74.0060, 40.7128]},
        {"type": "Point", "coordinates": [-73.9712, 40.7831]},
        {"type": "Point", "coordinates": [-73.9680, 40.7614]},
        {"type": "Point", "coordinates": [-73.9855, 40.7580]},
    ],
    mode="auto",
)
print(result["total_cost_s"])

import "github.com/plazafyi/plaza-go"

client := plaza.NewClient()

result, _ := client.V1.Optimize(ctx, plaza.OptimizeParams{
    Locations: []plaza.GeoJSONPoint{
        {Type: "Point", Coordinates: []float64{-73.9857, 40.7484}},
        {Type: "Point", Coordinates: []float64{-74.0060, 40.7128}},
        {Type: "Point", Coordinates: []float64{-73.9712, 40.7831}},
        {Type: "Point", Coordinates: []float64{-73.9680, 40.7614}},
        {Type: "Point", Coordinates: []float64{-73.9855, 40.7580}},
    },
    Mode: "auto",
})

Response

Response — a GeoJSON FeatureCollection with waypoints in optimized visit order:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-73.9857, 40.7484] },
      "properties": {
        "waypoint_index": 0,
        "cost_s": 0,
        "cumulative_cost_s": 0
      }
    },
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-73.9855, 40.7580] },
      "properties": {
        "waypoint_index": 4,
        "cost_s": 420,
        "cumulative_cost_s": 420
      }
    }
  ],
  "total_cost_s": 2940,
  "optimization": "tsp",
  "roundtrip": true
}

waypoint_index maps back to your input array. cost_s is travel time from the previous stop; cumulative_cost_s is the running total.

Large jobs (more than 10 stops)

Above 10 stops, the request runs asynchronously and returns a job ID:

curl -X POST https://plaza.fyi/api/v1/optimize \
  -H "x-api-key: pk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "waypoints": [
      { "type": "Point", "coordinates": [-73.9857, 40.7484] },
      { "type": "Point", "coordinates": [-74.0060, 40.7128] },
      { "type": "Point", "coordinates": [-73.9712, 40.7831] },
      { "type": "Point", "coordinates": [-73.9680, 40.7614] },
      { "type": "Point", "coordinates": [-73.9855, 40.7580] },
      { "type": "Point", "coordinates": [-73.9776, 40.7527] },
      { "type": "Point", "coordinates": [-73.9542, 40.7681] },
      { "type": "Point", "coordinates": [-73.9937, 40.7505] },
      { "type": "Point", "coordinates": [-73.9654, 40.7829] },
      { "type": "Point", "coordinates": [-73.9818, 40.7681] },
      { "type": "Point", "coordinates": [-73.9726, 40.7644] },
      { "type": "Point", "coordinates": [-73.9499, 40.7736] }
    ],
    "mode": "auto"
  }'

{
  "status": "processing",
  "job_id": "opt_8f3a2b1c"
}

Poll until it’s done:

curl https://plaza.fyi/api/v1/optimize/opt_8f3a2b1c \
  -H "x-api-key: pk_live_YOUR_KEY"

// The SDK handles polling for you
const result = await client.v1.optimize({
  locations: stops, // array of GeoJSON Point objects
  mode: "auto",
});
// Blocks until the job finishes, then returns the same response format

When done, the poll endpoint returns { "status": "completed", "result": { ... } } with the same FeatureCollection format. While running, it returns { "status": "processing" }.

Modes

Mode	Network
auto	Roads, one-ways, turn restrictions
foot	Sidewalks, footpaths, trails
bicycle	Bike lanes, cycleways, shared roads

Limits

Maximum 50 waypoints per request. Small jobs (up to 10) return in under a second. Larger ones scale roughly with the square of the stop count.

Round trips

By default, the route returns to the starting point. Set "roundtrip": false for an open-ended route:

{
  "waypoints": [
    { "type": "Point", "coordinates": [-73.9857, 40.7484] },
    { "type": "Point", "coordinates": [-74.0060, 40.7128] },
    { "type": "Point", "coordinates": [-73.9712, 40.7831] },
    { "type": "Point", "coordinates": [-73.9680, 40.7614] }
  ],
  "mode": "auto",
  "roundtrip": false
}