Guide du système¶
Ce guide explique comment les objets de l'API s'articulent : d'où vient la donnée, ce qui la transforme, et où la lire. Il complète le glossaire, qui définit chaque entité prise séparément.
Parcours de lecture¶
Les cinq pages se lisent dans cet ordre, qui suit le trajet de la donnée dans le système.
| Étape | Page | Ce qu'on y comprend |
|---|---|---|
| 1 | Référentiel GTFS | Comment l'offre théorique entre dans le système et quel GTFS fait foi |
| 2 | Courses | Ce qui distingue une course prévue d'une course réalisée, et comment la désigner sans ambiguïté |
| 3 | Temps réel | Comment le terrain remonte, et ce qui ressort vers les voyageurs |
| 4 | Exploitation | Qui conduit quoi, et comment le prévu se confronte au réalisé |
| 5 | Statistiques et exports | Comment sortir la donnée en masse pour l'analyser |
Une page reste en dehors de ce parcours : Gares ferroviaires décrit le référentiel des gares de voyageurs SNCF, le seul endpoint de l'API sans groupe et sans authentification. À lire si vous rattachez des arrêts de votre réseau à des gares ; à ignorer sinon.
Le groupe, préalable à tout appel¶
Un groupe est un réseau exploité, et l'unité d'isolation de l'API : presque tous les endpoints sont préfixés par /groups/<group_id>, et une donnée n'existe jamais en dehors du groupe qui la porte. Le premier réflexe, avant tout appel, est donc de savoir sur quel groupe on travaille.
Un intégrateur reçoit son <group_id> et une clé d'API portant les droits correspondants. La page Authentification décrit comment obtenir cette clé et la transmettre.
Chaque groupe porte aussi une classification, le champ kind : customer, demo, internal ou test. Un groupe jamais classifié n'a pas de valeur stockée et se lit customer. Seul un superutilisateur la modifie, par la route dédiée ci-dessous ; la mise à jour complète du groupe (PUT /api/v3/groups/<group_id>) conserve la valeur stockée, y compris un customer posé explicitement, quel que soit le kind envoyé.
| Endpoint | Rôle |
|---|---|
PUT /api/v3/groups/<group_id>/config/kind |
Classe le groupe (superutilisateur uniquement) |
Les deux temps du système¶
Toute la lecture de l'API repose sur une distinction. Elle traverse ce guide de bout en bout.
| Théorique | Réalisé | |
|---|---|---|
| Ce que c'est | Ce que le réseau prévoit | Ce qui s'est produit |
| Origine | Le GTFS importé | Les remontées des appareils des conducteurs |
| Change quand | Un nouveau GTFS est publié | En continu, pendant le service |
| Exemple | Une course part à 8 h 05 | Elle est partie à 8 h 09, deux arrêts non desservis |
Confondre les deux est l'erreur la plus fréquente à l'intégration : une même course a un horaire prévu et des heures de passage observées, et les deux se lisent à des endroits différents.
Un mot sur les versions¶
L'API est versionnée de v2 à v5 ; v4 est la version par défaut et celle que ce guide emploie. Le versionnement et les trois catégories d'endpoints (public, internal, datahub) sont décrits sur la page d'accueil.