System guide¶
This guide explains how the API's objects fit together: where the data comes from, what transforms it, and where to read it. It complements the glossary, which defines each entity on its own.
Reading order¶
The five pages are meant to be read in this order, which follows the data's path through the system.
| Step | Page | What it makes clear |
|---|---|---|
| 1 | GTFS reference | How the scheduled service enters the system and which GTFS prevails |
| 2 | Trips | What separates a scheduled trip from an operated one, and how to designate it unambiguously |
| 3 | Real time | How the field reports in, and what goes out to passengers |
| 4 | Operations | Who drives what, and how the forecast meets the record |
| 5 | Statistics and exports | How to pull the data in bulk for analysis |
One page sits outside that path: Rail stations describes the SNCF passenger-station referential, the only endpoint of the API that carries no group and needs no authentication. Read it when you attach stops of your network to rail stations; skip it otherwise.
The group, a prerequisite to every call¶
A group is an operated network, and the API's isolation unit: nearly every endpoint is prefixed with /groups/<group_id>, and a piece of data never exists outside the group that holds it. So the first thing to establish, before any call, is which group you are working on.
An integrator is given their <group_id> and an API key carrying the matching rights. The Authentication page describes how to obtain that key and pass it.
The system's two tenses¶
All reading of the API rests on one distinction. It runs through this guide from end to end.
| Scheduled | Actual | |
|---|---|---|
| What it is | What the network plans | What happened |
| Origin | The imported GTFS | The reports from drivers' devices |
| Changes when | A new GTFS is published | Continuously, during service |
| Example | A trip departs at 8:05 | It departed at 8:09, two stops not served |
Conflating the two is the most common mistake at integration time: one trip has a scheduled time and observed passing times, and the two are read in different places.
A word on versions¶
The API is versioned from v2 to v5; v4 is the default and the one this guide uses. Versioning and the three endpoint categories (public, internal, datahub) are described on the home page.