/shipments/{shipmentId}/legs/candidate-tours

Rank, per requested segment, the tours that segment could be routed onto. Candidates are ordered by feasibility SECTION first (fitsfits-with-caveatsdoes-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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

The ID of the shipment whose segments to rank for.

Body Params
segments
array
required
length between 1 and 10

The segments to rank candidate tours for — at least one, at most ten (the leg-plan cap). Each entry references a leg of the shipment or supplies a literal draft segment.

segments*
string
length between 1 and 120

Attribution key echoed back on the matching result entry. Defaults to the referenced leg's id. Must be unique across the request's segments.

string
required
length ≥ 1

Id of a leg of the shipment. The segment's endpoints, time window, and loads are resolved from this leg. A leg that does not belong to the shipment is rejected as a validation error.

boolean
Defaults to true

Whether to compute the per-candidate capacityFit (a 3D load-plan solve per candidate). Defaults to true; send false for cheap overview passes and re-request the focused segment with capacity when needed.

draftAssignedTourIds
array of strings
length ≤ 100

Tour ids a not-yet-committed staged plan assigns a leg of the shipment to. These tours stay listed in the rankings, flagged draftAssigned, instead of being excluded as already-carrying. Omit when no staged plan exists.

draftAssignedTourIds
integer
1 to 25

Maximum candidates to return per segment. Defaults to 6; 25 is the ceiling for the ranked list, and entries forced via includeTourIds are returned beyond it, so a response can exceed this value by up to five entries. Raise it when the ranking's top few tie on every signal (a hub network makes many tours equidistant) and lower it for cheap overview passes; with withCapacity on, each returned candidate costs one load-plan solve.

includeTourIds
array of strings
length ≤ 5

Tour ids whose candidate entries are guaranteed in each segment's response when the tour is rankable at all: a listed tour joins the ranking even when the proximity prefilter would skip it, and its entry is returned beyond limit at its true rank. Use to revalidate a specific tour a user already selected. Ineligible tours (settled, already carrying the shipment) are still excluded.

includeTourIds
Responses

400

Malformed request, a segment referencing a leg or load the shipment does not have, or a terminal shipment.

401

Unauthorized - invalid or missing API key.

404

Shipment not found.

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json