Rank, per requested segment, the tours that segment could be routed onto. Candidates are ordered by feasibility SECTION first (fits › fits-with-caveats › does-not-fit — decided by a schedule simulation against the requested stop windows, the load-plan capacity verdict, and the shipment's leg-chain deadline), then by INSERTION COST in added minutes within the section: insertionCost.addedMinutes is the detour of the cheapest ordered insertion of the segment's pickup and dropoff into the tour's existing route, plus a fixed price per genuinely NEW stop (a tour already stopping at a segment site pays one less), plus the driver waiting the insertion induces. At most one candidate is pinned: a caveat-section option drastically cheaper than the best clean one, surfaced directly under rank 1. Every fact that ranked or gates a candidate appears in its tags; the utilization object carries the container load from the same capacity solve. The synthetic baseline row prices running the segment as its own new tour with the same math and takes a real rank among the candidates; excluded counts the tours left out (settled, already carrying the shipment, wrong day), so nothing disappears silently. Render entries by their explicit rank, never by array position. regionMatch, timeOverlap, proximityKm, and directionMatch are the previous heuristic's signals — still returned for compatibility, but DEPRECATED: none of them orders the list anymore. A segment references a leg of the shipment ({legId}) or is supplied literally ({key, pickup, dropoff, shipmentLoadIds}) for a not-yet-persisted plan. One call ranks every segment; each result entry is attributed by the segment's key (defaulting to the leg id). At most six candidates per segment unless limit raises it (ceiling 25). Numbers are estimates while insertionCost.estimated is true (beeline distances scaled by a circuity factor calibrated from the tenant's own tours) — treat them as approximate. Read-only — nothing is written. A terminal (Cancelled or Delivered) shipment is rejected as a state error, never an empty ranking.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
400Malformed request, a segment referencing a leg or load the shipment does not have, or a terminal shipment.
401Unauthorized - invalid or missing API key.
404Shipment not found.
