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 trip_events and 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 |
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.