Multi-stop route total distance calculator

This calculator accepts the exact order in which places will be visited and a collection of known pairwise distances, then adds only the legs used by that route. It returns a transparent leg-by-leg breakdown alongside the total, and it stops with a clear error when a required connection is absent. Pair entries are treated as undirected, so one distance between two stops works for travel in either direction.

Describe the route and the available distances

Start with the stops array, listing every place in the precise visiting order. Names are matched after surrounding whitespace is removed, but letter case and internal spacing remain significant, so use consistent labels. A stop may appear more than once when a route returns to a depot or revisits a location. Next, provide distance records containing from, to, and distance. Each record describes an unordered pair: a value entered for Depot to Museum is also available for Museum to Depot. Distances must be finite, non-negative numbers, and all values must use the unit selected in distance_unit. The calculator does not convert mixed units because an apparently reasonable total made from kilometers and miles would be misleading. Extra pairs are allowed and ignored when they are not part of the requested visiting order. This makes it practical to submit a reusable distance table while changing only the route sequence. If the same pair appears more than once with different values, the request is rejected instead of silently selecting one of the conflicting measurements.

Understand how the route total is calculated

The calculation walks through the stops from left to right and considers each adjacent pair exactly once. For a sequence of Depot, Museum, Hotel, and Depot, the required legs are Depot–Museum, Museum–Hotel, and Hotel–Depot. The algorithm looks up each pair without regard to direction, adds its distance to a running total, and records the leg in the output. It never chooses a shorter route, inserts an unlisted place, or substitutes a path through another stop. This is a sequence total, not a routing or optimization engine, so the supplied order remains authoritative. Consecutive repeated names contribute a zero-distance leg because no travel occurs between a place and itself. The result includes total_distance, distance_unit, stop_count, leg_count, and the ordered legs used in the sum. A stable precision step limits insignificant floating-point artifacts while preserving useful decimal detail. Because every included value is shown, the total can be audited against the source table without reconstructing which connections the calculator selected.

Handle incomplete route data before it causes trouble

Before returning any total, the calculator verifies that every consecutive pair in the visiting order has a supplied distance. If Museum–Hotel is missing, it identifies those two stop names and rejects the request; it does not treat the gap as zero or return a partial total. That fail-closed behavior is useful in dispatch, itinerary preparation, mileage reimbursement, and delivery planning, where an understated distance can affect schedules or budgets. Correct the named pair, submit the request again, and the same deterministic inputs will always produce the same result. The check covers only legs that the sequence actually uses, so missing values between unrelated stops do not matter. Pairwise inputs can come from a road-distance matrix, a planning spreadsheet, surveyed trail segments, or another trusted source. The calculator does not contact a map provider and cannot determine whether those values reflect current roads, closures, toll restrictions, or a particular vehicle. Validate the source distances separately whenever operational decisions depend on real-world travel conditions.