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> |
Describes a GTFS and its validity |
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id>/validate |
Returns the validation report |
A GTFS's lifecycle reads from these three calls: an imported GTFS stays inactive until it is published, and archiving takes it out of service without destroying it.
| Endpoint | Purpose |
|---|---|
POST /api/v4/groups/<group_id>/gtfs |
Imports a new GTFS |
POST /api/v4/groups/<group_id>/gtfs/<gtfs_id>/publish |
Puts the GTFS into service |
POST /api/v4/groups/<group_id>/gtfs/<gtfs_id>/archive |
Takes the GTFS out of service |
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.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/frequencies |
Gives the declared frequencies |
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 |
Planning is a forecast. What was actually operated is read from the duty, described in the duties entry.