Fleet¶
The resources committed to running the service: who drives, with which vehicle, fitted with which device, out of which depot.
drivers¶
Driver — the person operating the trips. A driver is not a user of the operations interface: they identify themselves on the Pysae Driver app, when signing on.
Identifier <driver_id>. A driver carries a staff number, belongs to one or more teams, and can be archived when they leave the network — archiving removes them from current operations without erasing the history they are tied to.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/drivers |
Lists the group's drivers |
GET /api/v4/groups/<group_id>/drivers/<driver_id> |
Describes a driver |
GET /api/v4/groups/<group_id>/export/drivers |
Exports the drivers as CSV |
vehicles¶
Vehicle — the bus or coach operating on the network. It carries its fleet number, its licence plate, its type and energy, its capacity, and the on-board equipment fitted to it.
Identifier <vehicle_id>. A vehicle belongs to one or more teams and carries an operating status, which distinguishes a vehicle in service from one that is off the road.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/vehicles |
Lists the group's vehicles |
GET /api/v4/groups/<group_id>/vehicles/<vehicle_id> |
Describes a vehicle |
GET /api/v4/groups/<group_id>/vehicles/public |
Gives the data broadcastable to passengers |
GET /api/v4/groups/<group_id>/export/vehicles |
Exports the vehicles as CSV |
devices¶
Device — the driver's phone or tablet, running the Pysae Driver app. It reports the vehicle's position and the progress of the trip, and is therefore the source of all real-time data: without a device in service, a trip is not tracked.
Identifier <device_id>. A device is attached to the vehicle it travels in, and knows the trip it is operating at a given moment — designated by the triplet trip identifier, service date and gtfs_id. It also carries its own metadata: model, operating system, installed version of the app.
A device counts as connected as long as it has exchanged with the API within the delay configured on the group (two minutes by default, adjustable and distinct per equipment type). That exchange can be a position, but equally a trip change, a passenger count or a duty check-in: a device that loses its GPS signal but keeps talking stays connected. The time of the last exchange is carried by connected_at, as opposed to ts, which dates the last known position.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/devices |
Lists the group's devices |
GET /api/v4/groups/<group_id>/devices/<device_id> |
Describes a device and its current state |
GET /api/v4/groups/<group_id>/devices/online |
Lists the currently connected devices |
depot¶
Depot — the site where vehicles are parked, and from which they leave and to which they return. It serves as a reference for operations: the empty runs between the depot and the start of the trip are counted from it.
Identifier <depot_id>.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/depots |
Lists the group's depots |
duties¶
Duty — the period during which a driver operates the service, from sign-on to sign-off. It is the object that actually ties together a driver, a vehicle, a device and the trips operated.
Identifier <duty_id>. A duty always carries the device used, and references the driver and the vehicle committed. It contains the list of trips operated, the dead mileage covered, and the sign-on and sign-off information — including the answers to the checklist, where applicable.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/duties |
Lists the duties over a period |
GET /api/v4/groups/<group_id>/duties/<duty_id> |
Describes a duty and its trips |
Where planning forecasts, the duty records.
duty-checklist¶
Duty checklist — the list of checks a driver fills in when signing on or off: vehicle condition, cleanliness, faults observed. Its composition is configured per group, and the answers are kept in the corresponding duty.
No identifier of its own: the checklist is a group configuration.
This configuration is driven from the Pysae applications and is not published in the public spec.