Travel time estimates

POST /v1/route with "include": ["estimate"] gives every route an estimate: how long the train takes to run the route, from the line speeds along it and the train’s mass, power and braking. It is an estimate, not a timetable. It has no signals, no timetable margins, no other traffic and no speed restrictions other than the line speed. Use it to compare routes and trains, or to plan roughly. Do not use it to timetable trains.

Every route has duration_min too: the time at line speed, capped at the train’s maximum speed, plus reversal_min for each reversal. That is the time the route search minimises. It has no acceleration and no braking, so it is normally shorter than the estimate. One exception: where OSM has no maxspeed, duration_min assumes 80 km/h, while the estimate uses the RINF speed as sections does.

Request

curl -H "Authorization: Bearer $RAIL_API_KEY" -H 'Content-Type: application/json' \
  https://api.routing.gleisklar.de/v1/route -d '{
    "from": { "station": "AK" },
    "via":  [{ "station": "AN", "dwell_min": 5 }],
    "to":   { "station": "AL" },
    "profile": "freight-electric-de",
    "vehicle": { "mass_t": 2000, "brake_decel_ms2": 0.4 },
    "include": ["estimate", "sections", "speed_profile"]
  }'

Field	Meaning	Freight / passenger typical value
`vehicle.train_type`	`freight` or `passenger`. The typical values of this type fill in every field you leave out	passenger without a profile
`vehicle.mass_t`	Train mass, t	1,600 / 200
`vehicle.power_kw`	Rated traction power, kW; 85 % of it reaches the wheel	6,400 / 4,000
`vehicle.max_tractive_effort_kn`	Starting tractive effort, kN	300 / 200
`vehicle.max_accel_ms2`	Acceleration cap, m/s²	0.5 / 1.0
`vehicle.brake_decel_ms2`	Service braking, m/s²	0.5 / 0.8
`vehicle.rotating_mass_factor`	Effective mass / mass	1.06 / 1.08
`vehicle.davis_a_kn`, `davis_b_kn_per_kmh`, `davis_c_kn_per_kmh2`	Running resistance A + B·v + C·v² in kN, v in km/h	Scaled from the mass (below)
`vehicle.max_speed_kmh`	Speed limit min(line speed, this)	from the profile
`vehicle.train_length_m`	A speed limit applies until the rear of the train has left it	from the profile
`via[].dwell_min`	Standing time at this via point. Above 0, the via point is a stop	0: the train passes through
`include: "speed_profile"`	Adds `estimate.speed_profile` for charts	not included
`include: "sections"`	Adds `sections`, and with them `estimate.segments`	not included

Every preset in GET /v1/route/profiles has values for these fields. They are typical values, not those of a particular vehicle: the electric freight presets use 1,600 t, 6,400 kW and 300 kN. The diesel freight preset uses 1,200 t, 2,400 kW and 300 kN. The EMUs use 200 t and 4,000 kW, and the DMU 120 t and 1,200 kW. Any field you set replaces the preset’s value. The vehicle in the response shows the values the estimate used.

Response

A route of the response, shortened, with illustrative values:

{
  "distance_km": 93.7,
  "duration_min": 72.4,
  "reversals": 0,
  "estimate": {
    "is_estimate": true,
    "total_min": 91.8, "running_min": 86.8, "dwell_min": 5, "reversal_min": 0,
    "stops": 1, "avg_speed_kmh": 61.2, "top_speed_kmh": 100,
    "method": "minimum running time: …",
    "note": "Estimated running time from line speeds and the train's characteristics …; not a timetable …",
    "gradients": {"known": false, "note": "No gradients along this route …"},
    "segments": [
      {"from_km": 0, "to_km": 1.234, "speed_limit_kmh": 60, "top_speed_kmh": 60, "avg_speed_kmh": 31.5, "time_s": 141}
    ],
    "speed_profile": [[0, 0, 60], [0.025, 9.8, 60], …]
  },
  "legs": [
    {"from": 0, "to": 1, "distance_km": 38.2, "duration_min": 30.1, "reversals": 0,
     "estimate": {"total_min": 36.2, "running_min": 36.2, "reversal_min": 0}},
    …
  ],
  "sections": [ … ]
}

total_min = running_min + dwell_min + reversal_min.
segments has one entry for each entry of sections, with the same km. time_s is the running time over the section, without stops. speed_limit_kmh is min(line speed, max speed).
legs[].estimate is each leg’s running time plus the reversals within the leg. Time standing at via points counts only in the route’s estimate. So the legs add up to the total minus that standing time.
speed_profile lists [km, km/h, line speed limit km/h] points. A point is added where the train starts or stops accelerating, cruising or braking, where its speed changes by 2 km/h, and where the limit changes.
The distance matrix, isochrones and route optimization use duration_min’s kind of time, not this estimate.

The model

The estimate is the classic minimum running time calculation, computed in 25 m steps:

Speed limit. The limit is the line speed, capped at the train’s max_speed_kmh. The line speed is taken in the same order as the sections: OSM maxspeed, then RINF, then 80 km/h. When the train passes from a lower limit to a higher one, the lower limit applies until the rear of the train has left it, which is train_length_m beyond the change.
Acceleration. a(v) = min(a_max, (min(F_max, P·η/v) − R(v) − m·g·i) / (m·ρ)). F_max is the starting tractive effort, P·η the power at the wheel (η = 0.85), and R(v) = A + B·v + C·v² the running resistance. i is the gradient (0 for now, see below) and ρ the rotating mass factor.
Braking at a constant service deceleration. It does not change with the gradient.
Cruising at the limit. The forward pass accelerates as hard as the train can. The backward pass brakes in time for every lower limit and every stop. The speed at each point is the lower of the two.
Stops. The train stops at the start, at the end, at every via point whose dwell_min is above 0, and at every reversal. A reversal adds reversal_min (default 20). At a via point where the train reverses, it stands for the longer of the dwell and the reversal time.

Typical resistance, as a share of the train’s weight (v in km/h):

Freight: 1.5 ‰ + 0.025·(v/10)² ‰. This is the Strahl formula for loaded wagons.
Passenger: 2.6 + 0.022·v + 0.00065·v² kN for a 200 t EMU, scaled with the mass.

If you change mass_t and do not set the davis_* coefficients, the resistance scales with the new mass.

Limits

No gradients. The track counts as level: OpenStreetMap rarely has gradients on railways, and RINF’s gradient profiles per track and section of line are not merged into the network yet (their positions would first have to be placed on the OSM track). estimate.gradients.known says whether gradients were used, and gradients.note explains it. On steep lines, heavy trains take longer than estimated.
Line speed only. The estimate has no temporary speed restrictions, no lower speeds through junctions or stations, no signals and no ETCS or LZB braking curves.
Stops only at via points. The train does not stop at stations along the route unless you make them via points with a dwell_min.
Typical train values. Real trains differ. For a closer estimate, give the train’s mass, power, tractive effort and braking.
No timetable margins. Timetables add recovery time (typically a few per cent) and time for construction work. Real trains also meet other traffic. Add margins yourself if you need them.