Operations¶
Running the service means assigning resources to trips, then recording what was actually done. The API exposes both, and it is their comparison that carries value.
Forecast, then record¶
Two objects look alike and answer different questions.
| planning | duties | |
|---|---|---|
| Answers | Who was due to operate what | Who actually operated the service |
| Nature | Forecast | Record |
| Produced by | The operator's planning | The driver signing on their device |
Comparing the two yields the operating gaps: an uncovered trip, a driver change, a substituted vehicle. No endpoint computes that comparison — it is up to the integration, by matching the two readings on the same date.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/planning |
Gives the forecast assignment over a period |
GET /api/v4/groups/<group_id>/duties |
Lists the duties actually operated |
GET /api/v4/groups/<group_id>/duties/<duty_id> |
Describes a duty and the trips it covers |
The duty ties everything together¶
The duty is the pivot of operations: for a given time span, it associates a driver, a vehicle, a device and a list of trips operated. It also carries the mileage covered outside commercial service, and the sign-on and sign-off information.
It is therefore the way in for any question of the form "who was driving this vehicle at such a time", which neither the trip nor the device answers on its own.
The resources¶
Three entities describe the resources committed, defined in the glossary: drivers, vehicles and devices.
Two points matter for an integration:
- A driver is not a user. They do not log into the operations interface; they identify themselves on the Pysae Driver app. User accounts belong to organization.
- Archiving is not deletion. A driver or a vehicle leaving the network is archived: they disappear from current operations, but stay attached to the history they produced. An integration filtering without accounting for archiving loses past data.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/drivers |
Lists the drivers |
GET /api/v4/groups/<group_id>/vehicles |
Lists the vehicles |
Partitioning by team¶
A group can be subdivided into teams — a depot, an area, a subcontractor. Drivers and vehicles are attached to them, and a user's rights may be limited to some of them.
An integration whose API key is restricted to teams only sees part of the network. An unexplained volume discrepancy is therefore checked on that side first.
Next¶
To analyse all of this over long periods, the way is bulk export — see Statistics and exports.