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¶

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.

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. punctuality et trip-tracking tolèrent aussi AAAA-MM-JJ, mais trips, trip-km et passenger-counts la 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.

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.

Détail des lignes à la demande¶

GET /api/v4/groups/<group_id>/export/on-demand-routes/details renvoie un CSV séparé par des points-virgules, avec une ligne par comptage voyageur, triée par date puis passed_at croissant, plus les lignes décrites ci-dessous pour les sessions de service et les kilomètres. start_date et end_date sont requis au format AAAAMMJJ et bornent les dates de service, bornes incluses. route_id et teams sont facultatifs ; les restrictions d'équipes du lecteur s'appliquent comme sur les statistiques.

Les colonnes sont, dans cet ordre : date, passed_at, route_id, route_short_name, stop_id, stop_name, vehicle, boarding, alighting, tranche_horaire, route_long_name, stop_lat, stop_lon, service_id, service_start, service_end, service_km. date est la date de service au format AAAA-MM-JJ ; passed_at est un instant ISO 8601 avec le décalage du fuseau du groupe. Plusieurs comptages au même arrêt ou au même instant restent des lignes distinctes. tranche_horaire est l'heure locale de passed_at, borne basse incluse (08:00-09:00). stop_lat, stop_lon et route_long_name sont ceux de la ligne dans sa configuration actuelle, et les coordonnées sont vides pour un arrêt retiré.

Une session de service sans aucun comptage a sa propre ligne (arrêt et heure vides, 0 boarding et alighting). service_id, service_start et service_end (heure locale, vide tant que le service est ouvert) identifient la session de chaque ligne. service_km donne les kilomètres de la session pour un jour local, sur la première ligne de cette session ce jour-là et vide sur les autres, pour que sa somme ne compte jamais deux fois ; une session qui passe minuit porte ses kilomètres sur chacun des deux jours, et un jour de kilomètres sans comptage a sa propre ligne. Les kilomètres enregistrés avant l'identification des sessions arrivent en lignes au service_id vide, une par jour, ligne et appareil. Une session commencée avant la période n'est listée que par les comptages et les kilomètres qu'elle a dedans. Une période vide ne produit que l'en-tête.

Le véhicule est celui du service de la même tablette et de la même ligne contenant le passage : début inclus, fin exclue ; un service sans fin reste ouvert, même s'il a commencé plusieurs jours avant la période exportée. En cas de chevauchement, le service commencé le plus récemment l'emporte. vehicle est vide sans service correspondant ou sans véhicule connu ; sinon il affiche l'immatriculation et le numéro de parc, en conservant seulement les parties renseignées. Un arrêt retiré de la ligne conserve son comptage, avec stop_name vide.

Les sommes de service_km, boarding et alighting par date et par ligne retrouvent celles de export/on-demand-routes avec les mêmes filtres. Les deux exports demandent les mêmes rôles de lecture des statistiques et les fonctionnalités ON_DEMAND et DEVICE_EVENT_SOURCING activées sur le groupe. Le bouton de téléchargement dans Op est livré séparément.

Exports asynchrones¶

Pour les périodes longues, un export peut être préparé en arrière-plan plutôt que diffusé dans la réponse : POST /api/v4/groups/<group_id>/exports crée la tâche et répond 202 avec un job_id ; GET /api/v4/groups/<group_id>/exports/<job_id> en donne l'état (pending, running, succeeded ou failed) et, une fois succeeded, une URL de téléchargement signée, renouvelée à chaque lecture. Une tâche n'est visible que de celui qui l'a demandée et disparaît au bout de trente jours, avec son fichier.

Le corps de la demande porte export_type et params. Le fichier produit est le même CSV que celui de l'export synchrone correspondant, avec les mêmes droits : un rôle refusé par l'endpoint synchrone fait échouer la tâche, sans fichier.

Un paramètre invalide est refusé par une erreur 422, sans créer de tâche. Les endpoints synchrones restent disponibles et inchangé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.