Route Optimization Max Distance Between Destinations

It is used to keep routes geographically tight and prevent long jumps between deliveries.

The optional maxDistanceBetweenStops parameter limits how far a driver travels between two consecutive stops on an optimized route. Use it to keep routes geographically tight and prevent long jumps between deliveries. If you leave it out, optimization works the same as today.

Example Request

curl -X POST "https://onfleet.com/api/v2/optimizations/scheduled" \
     -u "<your_onfleet_api_key>:" \
     -H "Content-Type: application/json" \
     -d '{
  "maxTasksPerRoute": 30,
  "date": 1793733492000,
  "timezone": "America/Vancouver",
  "mode": 0,
  "serviceTime": 5,
  "tasks": [
    "im2whAHMidABSqmqc1v7EFX9",
    "eMUPZT9uXFls78jMjMlsP0br",
    "FP~zFUsG25rdY8FJ6v3xVYsx"
  ],
  "teams": {
    "9PVeSqj*RxI46~aD*M812DkY": ["mQpa~QD~LYcG89bPdig8sREj"]
  },
  "schedulingMethod": 1,
  "routeStart": "teams://DEFAULT",
  "routeEnd": "teams://DEFAULT",
  "maxViolationTime": 0,
  "maxDistanceBetweenStops": 2.5,
  "maxDistanceBetweenStopTypes": "DROPOFF",
  "defaultSchedule": [
    {
      "date": 1793733492000,
      "slots": [{ "start": "0000", "end": "2359" }],
      "owner": "gz6~YVrx7HVI34ecvWOG1LfB",
      "timezone": "America/Vancouver"
    }
  ]
}'

On a metric organization, this request keeps every leg between two dropoff stops to 2.5 km of driving or less. Legs to and from pickup stops are not limited.

Route Optimization Behaviour

Driving distance: The limit is measured by road, not in a straight line. Two stops 3 km apart across a river with no nearby bridge may be 9 km apart by road.

Hub legs are not limited: Travel from the route start to the first stop, and from the last stop to the route end, is not counted. A tight group of stops far from your hub can still be routed.

Stop types: With ALL (or when omitted), the limit applies between every pair of consecutive stops. With PICKUP or DROPOFF, the limit applies only to legs where both stops are of that type. For example, with DROPOFF, a leg from a dropoff to a pickup is not limited.

Stops that can't meet the limit: A task that is farther than the limit from every other stop can't share a route with them. If a driver is available, the optimizer may give that task its own one-stop route, because a single-stop route has no stop-to-stop leg. If no driver is available, the task is left unassigned.

Finding unassigned tasks: After the optimization finishes, Get Optimization Status returns the IDs of unassigned tasks in unassignedTasks, and each worker's planned stop order in summary.workers.<workerId>.tasks. No reason is given for why a task was left unassigned. If tasks are unexpectedly unassigned, increase the limit or remove it.

Errors

Validation errors return HTTP 400 with error code 1000. The specific reason is in message.cause:

{
  "code": "InvalidContent",
  "message": {
    "error": 1000,
    "message": "The values of one or more parameters are invalid.",
    "cause": "Invalid maximum distance between stops"
  }
}