GTFS reference¶
Everything starts here. GTFS describes the network's scheduled service — routes, stops, shapes, calendars, timetables — and it is what gives their identity to the trips the API exposes afterwards.
A group keeps several GTFS¶
A GTFS is not imported once and for all. A network changes its service every season, for every roadworks, for every adjustment. This is not a new version of an existing GTFS: it is a new GTFS, with a new identifier. The group therefore accumulates distinct GTFS, each published for its validity range.
The practical consequence matters: a date determines the GTFS in force. Asking for a trip's timetable without knowing which GTFS it belongs to is meaningless as soon as you step outside the current day.
| 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>/history/gtfs-active |
Gives the GTFS in force on a past date |
For an integration working on historical data, the third endpoint is the way in: it saves you from reconstructing the mapping between a date and a GTFS yourself.
A GTFS's lifecycle¶
An imported GTFS does not enter service immediately. It is validated first, then published; archiving takes it out of service without destroying it, so that the data produced while it was active stays interpretable.
This is why an archived GTFS remains readable: trips operated six months ago belong to the GTFS that was in force then, not to today's.
| Endpoint | Purpose |
|---|---|
GET /api/v4/groups/<group_id>/gtfs/<gtfs_id>/validate |
Returns a GTFS's validation report |
What the reference holds¶
Three GTFS objects come up constantly in the API, defined in the glossary:
- gtfs — the GTFS itself;
- trips — the scheduled trips;
- stop_times — their passing times at stops.
Routes, stops and shapes also exist in the reference, but the public API exposes them through trips rather than as collections of their own: you read a trip's stops, not the catalogue of stops.
Next¶
Once the GTFS in force is known, a trip can be designated unambiguously — that is the subject of the Trips page.