Statistics and exports¶
To analyse the service over long periods, you do not walk the per-item endpoints: the API exposes bulk outputs, in two shapes.
Two shapes, two uses¶
| Shape | Path | What it returns | For what |
|---|---|---|---|
| Aggregate | /stats/<domain> |
Values already computed over the period | Dashboard, tracked indicator |
| Export | /export/<domain> |
The detail, row by row | Data warehouse, reprocessing |
The choice follows the need: an aggregate saves you from recomputing what the API already knows how to do, an export gives the raw material for analyses the API does not provide.
The eight exports¶
These eight endpoints make up the datahub category, intended to feed a data warehouse.
| Export | Expected parameters |
|---|---|
export/trips |
date (required) |
export/trip-km |
start_date, end_date (required) |
export/passenger-counts |
start_date, end_date (required) |
export/punctuality |
start_date (required), end_date, and optional filters (event, stop_id, gtfs_id, driver_id, route_id) |
export/trip-tracking |
start_date, end_date (required) |
export/drivers |
archived (optional) |
export/vehicles |
statuses (optional) |
export/alerts |
none |
Three points to read carefully before writing a client:
- The exports do not share the same signature. Some bound a period, one takes a single date, three take none. There is no generic call to write once for all eight.
- Write dates in the compact
YYYYMMDDform. It is the only one all five dated endpoints accept.punctualityandtrip-trackingalso tolerateYYYY-MM-DD, buttrips,trip-kmandpassenger-countsreject it — and the last two answer with a server error rather than a validation error. - The perimeter follows the key's rights. A key restricted to certain teams exports fewer rows than expected, with nothing in the response to say so.
All eight endpoints return CSV. The spec nevertheless declares application/json for export/trips: that is a declaration defect, the content served is indeed CSV.
The aggregates¶
The same domains exist in computed form, under /stats/, with the same period parameters.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/stats/punctuality |
Punctuality aggregated over the period |
GET /api/v4/groups/<group_id>/stats/trip-km |
Kilometres covered |
GET /api/v4/groups/<group_id>/stats/passenger-counts |
Ridership |
GET /api/v4/groups/<group_id>/stats/vehicles-used |
Vehicles committed |
Querying the past¶
An export covers a closed period. To reconstruct an elapsed day in detail — events reported, passings observed, GTFS then in force — query the history instead.
The reminder from the GTFS reference page fully applies here: data from six months ago is interpreted against the GTFS in force at that date, not against today's.
Good practice¶
- Split long periods. An export over a whole year produces a large response and a long request; chaining monthly slices is safer and resumes after a failure.
- Do not set a short timeout. These responses are streamed, and a wide export takes time to start.
- Replaying an export has no side effect. These endpoints are read-only: when in doubt about a slice, asking for it again costs only the transfer.
The matching code examples, in the language selected in the header, are on the Collection examples page.