Network¶
The schedule reference: what the network plans to do. It comes from the imported GTFS and only changes when a new GTFS is published.
gtfs¶
GTFS — the dataset describing the network's scheduled service: routes, stops, shapes, calendars and timetables. An industry-standard format, it is imported into the group then published to become the reference in force.
Identifier <gtfs_id>. A group keeps several GTFS: the one in service, the previous ones, and the upcoming ones. They are not versions of one GTFS — when the service changes, a new GTFS is imported, with a new identifier. Each is published for a validity range, so a given date determines the GTFS in force. Trips, stop times and frequencies belong to a specific GTFS — which is why a trip is designated by its identifier and its gtfs_id.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/gtfs |
Lists the group's GTFS |
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id> |
Downloads the zip archive of a GTFS (anonymously once published or shared) |
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id>/validate |
Returns the validation report |
trips¶
Trip — a journey scheduled on a route, with its itinerary and its passing times. It is the central object of operations: trips are planned, assigned, tracked, and their execution is measured.
Identifier <trip_id>, which comes from GTFS. A trip alone is not enough to designate a real journey: it takes the triplet trip identifier, service date and gtfs_id, since a trip identifier is only unique within its GTFS and the trip repeats on every operating day. The three together form a unique key: the triplet designates one and only one trip run.
| 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>/export/trips |
Exports the operated trips as CSV |
stop-times¶
Stop time — the scheduled passing times of a trip at each of the stops it serves, in order. This is what makes it possible to say that a vehicle is early or late: the gap is always measured against the scheduled time of the stop concerned.
No identifier of its own: a stop time is designated by its trip and the rank of the stop in the sequence.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/stop-times |
Gives the scheduled times at stops |
The times actually observed are kept separately, described in the history entry.
frequencies¶
Frequency — a way of describing service where a trip is given not by exact times but by a headway over a time span, for example a bus every ten minutes from 7 a.m. to 9 a.m. A standard GTFS notion, used on high-frequency routes.
No identifier of its own: a frequency belongs to a trip and a time span.
This data is served to the Pysae Driver app and is not published in the public spec.
planning¶
Planning — the forecast assignment of resources to trips: which driver and which vehicle operate which trip, on which date. It is the bridge between the schedule reference and the group's actual resources.
No identifier of its own: a planning line is designated by its trip and its date. It references a driver, a vehicle, and possibly a block — the sequence of trips chained by a single vehicle.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/planning |
Gives the forecast assignment over a period |
PUT /api/v4/groups/<group_id>/planning |
Records the forecast assignment |
An import referencing a driver (staff_number) or a vehicle (license_plate) the group does not have is refused as a whole: the 422 response lists, under detail.missing, the drivers and vehicles not found. With force=true, the other lines are imported anyway; those referencing a missing driver or vehicle are left out, and the response lists both the recorded assignments (inserted) and what was not found (missing). The import is still refused when no line is left.
Planning is a forecast. What was actually operated is read from the duty, described in the duties entry.