Trips¶
The trip is the central object of operations. It is also the least simple to designate: a trip identifier, on its own, is never enough.
The identifying triplet¶
A trip is designated by three pieces of information:
| Element | Why it is needed |
|---|---|
| The trip identifier | It comes from GTFS and names the journey in the transport plan |
| The service date | The same trip runs on every operating day |
The gtfs_id |
A trip identifier is only unique within its GTFS; you therefore need to know which GTFS it belongs to |
Omitting the date amounts to asking for "trip 4218" without saying which day; omitting the gtfs_id amounts to asking for its times without saying under which transport plan. Both omissions produce plausible but wrong results — the costliest trap at integration time.
The three together form a unique key: the triplet designates one and only one trip run, it never appears twice.
Scheduled and actual¶
A trip carries both of the system's tenses at once.
| Where it is read | What it gives | |
|---|---|---|
| Scheduled | The reference's timetables, see stop-times | The time the trip was due at each stop |
| Actual | The devices' reports, see history | The time it actually passed |
Delay is not a separately stored value: it is the gap between those two readings, stop by stop. Punctuality is its aggregate over a period.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/trips |
Lists the trips over a period |
GET /api/v4/groups/<group_id>/trips/<trip_id> |
Describes a trip |
GET /api/v4/groups/<group_id>/stop-times |
Gives the scheduled times at stops |
Observed stop passages¶
An arrival is the transition into the stopped state; subsequent reports while waiting do not create another arrival. A departure is the transition out of that state towards the next stop, including when intermediate stops are skipped. GPS oscillation towards the same stop and residual state from a previous trip do not confirm a departure.
When several passages are observed at the same stop, the one with the smallest absolute difference from the scheduled time is retained. Punctuality history, v5 trip tracking and the GTFS-RT feed share this rule. It can correct v5 punctuality statistics and GTFS-RT times, particularly when GPS drift had produced an early departure at a terminus.
Older v5 trips remain readable using their historical departure inference. They are not recalculated retrospectively. The backfill_first_stop_departures migration can correct first-stop departures from history passages, choosing the closest to the schedule; it does not replay entire trips.
What the operator can change¶
The reference is not rewritten on every incident. A disruption becomes a trip update that overlays the schedule for a period: a stop skipped, moved or added, a trip diverted or cancelled. See trip-updates.
An integrator does not read those updates directly — they are not published in the public spec — but sees their effect in the real-time feeds described on the next page, and in the operated trips.
Versions v4 and v5¶
v4 is the API's default version and the one this guide uses.
v5 rewrites how trips are read, on top of the events reported by the devices rather than a recomputed state: the operated trip is reconstructed from the sequence of observed facts. That mode is enabled group by group, and its endpoints are not published in the public spec as of today — so an external integration works in v4.
| Endpoint | Purpose |
|---|---|
GET /api/v5/groups/<group_id>/trips |
Lists the trips reconstructed from the events |
Next¶
What remains is where the reports feeding the actual side come from — that is the subject of the Real time page.