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.

Viewing and downloading a GTFS without authentication¶

The list of a group's GTFS is public: it also shows upcoming offers and drafts. An anonymous call gets neither the author of the last change (mod_user), nor the validation report (validation), nor the failure of a scheduled publication (publication_failed): these fields require a read role on the group. The archives themselves can be downloaded without an account in two cases.

Any other GTFS — draft, scheduled offer, never-shared import — requires a read role on the group; an anonymous call gets 403 NO_ROLE, unknown identifiers included. The public_download field of a GTFS tells whether it has been shared.

Both archive endpoints answer with an ETag and a Last-Modified header, and support conditional requests: send the ETag back in If-None-Match (or the date in If-Modified-Since) and an unchanged archive is answered with an empty 304 Not Modified, without being rebuilt. If-None-Match takes precedence when both headers are sent. The ETag also changes when a team of the group is renamed, which Last-Modified does not reflect.

Sharing is set from the Pysae applications, by the operator: PUT /api/v4/groups/<group_id>/gtfs/<gtfs_id>/metadata with {"public_download": true}. It serves files prepared for an open-data portal without being put into service. A published GTFS stays downloadable whatever this setting.

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.

Validation relies on a dedicated checking service. If it does not answer in time, the call returns 504 GTFS_VALIDATOR_TIMED_OUT; if it is unreachable or answers with an error, 502 GTFS_VALIDATOR_UNAVAILABLE. In both cases the GTFS itself is not at fault: the report stays pending and the call can be retried later.

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.