Statistiques et exports¶
Pour analyser le service sur des périodes longues, on ne parcourt pas les endpoints unitaires : l'API expose des sorties en masse, sous deux formes.
Deux formes, deux usages¶
| Forme | Chemin | Ce qu'elle renvoie | Pour quoi |
|---|---|---|---|
| Agrégat | /stats/<domaine> |
Des valeurs déjà calculées sur la période | Tableau de bord, indicateur suivi |
| Export | /export/<domaine> |
Le détail ligne par ligne | Entrepôt de données, retraitement |
Le choix se fait sur le besoin : un agrégat évite de recalculer ce que l'API sait déjà faire, un export donne la matière pour des analyses que l'API ne prévoit pas.
Les huit exports¶
Ces huit endpoints constituent la catégorie datahub, prévue pour l'alimentation d'un entrepôt de données.
| Export | Paramètres attendus |
|---|---|
export/trips |
date (requis) |
export/trip-km |
start_date, end_date (requis) |
export/passenger-counts |
start_date, end_date (requis) |
export/punctuality |
start_date (requis), end_date, et des filtres facultatifs (event : arrival ou departure, stop_id, gtfs_id, driver_id, route_id) |
export/trip-tracking |
start_date, end_date (requis) |
export/drivers |
archived (facultatif) |
export/vehicles |
statuses (facultatif) |
export/alerts |
aucun |
Trois points à lire attentivement avant d'écrire un client :
- Les exports ne partagent pas la même signature. Certains bornent une période, un seul prend une date unique, trois n'en prennent aucune. Il n'y a pas d'appel générique à écrire une fois pour les huit.
- Écrire les dates au format compact
AAAAMMJJ. C'est le seul accepté par les cinq endpoints datés.punctualityettrip-trackingtolèrent aussiAAAA-MM-JJ, maistrips,trip-kmetpassenger-countsla rejettent par une erreur de validation. - Le périmètre suit les droits de la clé. Une clé restreinte à certaines équipes exporte moins de lignes qu'attendu, sans que rien ne le signale dans la réponse.
Les huit endpoints renvoient du CSV. Le spec déclare toutefois application/json pour export/trips : c'est un défaut de déclaration, le contenu servi est bien du CSV.
Kilomètres par course¶
Le comptage unique décrit ci-dessous est activé progressivement par réseau, après information des utilisateurs des exports. Tant qu’il n’est pas activé pour votre réseau, les kilomètres théoriques et les déviations restent comptés sur chaque prise comme auparavant.
Quand plusieurs appareils ont roulé la même course le même jour, l'export conserve toutes les lignes et leurs kilomètres réalisés. Les kilomètres théoriques sont comptés une seule fois, sur la ligne ayant le plus de kilomètres réalisés. En cas d'égalité, la prise commencée le plus tôt est retenue ; un début connu passe avant un début absent, puis l'identifiant de l'enregistrement départage les égalités restantes de façon stable.
Les lignes secondaires portent theoretical_commercial_km à zéro. Le delta deviated_km et le total theoretical_commercial_km_with_deviation suivent la même règle ; une valeur non mesurée reste vide. Les statistiques par jour et par ligne comptent elles aussi uniquement la déviation de la prise principale. Les kilomètres réalisés et le dénominateur nominal du taux de réalisation restent inchangés.
Cette règle s'applique également aux exports historiques : leurs totaux théoriques peuvent donc diminuer. Dans Excel, Power BI ou une autre intégration, protéger les divisions réalisées ligne par ligne contre un théorique nul. Le format et le nombre de lignes du CSV sont conservés.
Pour l'export de ponctualité, les passages d'une course sont ordonnés par instant, puis par numéro d'arrêt, avec l'arrivée avant le départ lorsque les deux événements partagent le même instant. Les courses ex æquo selon les clés de départ sont départagées par identifiants GTFS, course et date de service. À paramètres et données égaux, cet ordre rend le CSV reproductible, y compris la colonne distance.
Les agrégats¶
Les mêmes domaines existent en version calculée, sous /stats/. Ils bornent la période par start_date et end_date au format AAAAMMJJ, sauf stats/punctuality, qui prend from et to en timestamp Unix exprimé en secondes. Une date AAAAMMJJ passée à from ou to y est refusée par une erreur 422, comme toute valeur antérieure au 1er janvier 2015.
| Endpoint | Rôle |
|---|---|
GET /api/v4/groups/<group_id>/stats/punctuality |
Ponctualité agrégée sur la période |
GET /api/v4/groups/<group_id>/stats/trip-km |
Kilomètres parcourus |
GET /api/v4/groups/<group_id>/stats/passenger-counts |
Fréquentation |
GET /api/v4/groups/<group_id>/stats/vehicles-used |
Véhicules engagés |
Interroger le passé¶
Un export porte sur une période close. Pour reconstituer une journée déjà écoulée dans le détail — événements remontés, passages observés, GTFS alors en vigueur — c'est l'historique qu'il faut interroger.
Le rappel de la page Référentiel GTFS vaut ici pleinement : les données d'il y a six mois s'interprètent selon le GTFS qui était en vigueur à cette date, pas selon celui d'aujourd'hui.
Bonnes pratiques¶
- Découper les longues périodes. Un export sur une année entière produit une réponse volumineuse et une requête longue ; enchaîner des tranches mensuelles est plus sûr et se reprend en cas d'échec.
- Ne pas fixer de délai d'attente court. Ces réponses sont diffusées au fil de l'eau et un export large met du temps à commencer.
- Rejouer un export est sans effet de bord. Ces endpoints sont en lecture seule : en cas de doute sur une tranche, la redemander ne coûte que le transfert.
Les exemples de code correspondants, dans le langage sélectionné dans l'en-tête, sont sur la page Exemples de collecte.