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, 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 — et les deux derniers répondent par une erreur serveur plutôt que 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.
Les agrégats¶
Les mêmes domaines existent en version calculée, sous /stats/, avec les mêmes paramètres de période.
| 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.