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.

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.

Import and the state transitions are reserved for the Pysae applications: POST /api/v4/groups/<group_id>/gtfs, then .../publish, .../archive and .../restore.

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.