Concepts

Cette page définit les mots employés partout ailleurs : identifiants, arrêts et zones d'arrêt, fraîcheur, unités, enveloppe de réponse et gestion du temps.

Identifiants#

Chaque identifiant est une chaîne opaque de la forme {network}:{kind}:{ref}, où kind vaut line, stop, area, trip, vehicle ou alert et ref est l'identifiant propre à l'opérateur, qui peut lui-même contenir :. Ne découpez que sur les deux premiers deux-points. Exemples : tbm:line:59, tbm:stop:3824, tbm:area:BEPIS66, idfm:line:C01371, idfm:area:71264, sncf:area:87581009, star:line:0006, tisseo:area:SA_1715.

Les identifiants restent stables d'un rafraîchissement à l'autre tant que l'opérateur conserve ses références. Ils peuvent être passés tels quels dans le chemin ou encodés (tbm%3Astop%3A3824) ; les deux formes fonctionnent.

Arrêts et zones d'arrêt#

Un arrêt (kind: "stop") est un point d'arrêt physique, en général un quai ou un côté de rue. Une zone d'arrêt (kind: "area") regroupe les points d'arrêt qui partagent un nom et un lieu, par exemple les deux quais d'une station de tram. Les zones ont des children ; les arrêts ont un parent_id. Les endpoints de passages acceptent les deux : une zone agrège les passages de tous ses enfants, ce que veulent la plupart des affichages « prochains passages ».

Lignes et directions#

Une Line a un code (ce qui est écrit sur le véhicule), un name, un mode, des couleurs en #RRGGBB et des directions. Dans les listes, les directions ne portent que id, name et headsign ; GET /lines/{id} et GET /lines/{id}/stops ajoutent les stops ordonnés. Les identifiants de direction valent 0 et 1 quand l'opérateur suit les conventions GTFS, ou sa propre référence sinon. Les modes sont tram, metro, bus, rail, coach, ferry, funicular, cable, other.

Fraîcheur#

Quavsit n'invente jamais de temps réel. Chaque Departure porte realtime (booléen) et status ; meta.freshness résume la liste :

Un passage théorique a expected_at: null, delay_seconds: null, realtime: false et status: "unknown", sauf si l'opérateur le marque explicitement à l'heure. Une réponse stale positionne aussi freshness: "stale" sur l'entrée meta.sources[] concernée et ajoute l'en-tête Warning: 110 quavsit "stale".

Passages et statut#

status vaut on_time, delayed, early, cancelled ou unknown. scheduled_at est l'heure théorique, expected_at la prévision temps réel quand elle existe, delay_seconds leur différence. Les listes sont triées par expected_at, à défaut scheduled_at. source nomme le flux d'origine (par exemple tbm:xtradata:horai ou gtfs-rt:trip_updates).

Véhicules et positions estimées#

Vehicle.position_source vaut gps quand l'opérateur publie des positions, et estimated quand Quavsit place le véhicule sur le tracé de la ligne entre son arrêt précédent et son arrêt suivant, au prorata du temps écoulé d'un trip update temps réel (Tisséo dans cette version). Les positions estimées sont une approximation pour l'affichage ; ne les utilisez pas pour des calculs de distance ou de vitesse. Les réseaux sans l'un ni l'autre répondent 404 capability_unsupported sur les endpoints véhicules.

Perturbations#

Une Alert a une severity (info, warning, critical), un title, un message optionnel, les line_ids et stop_ids concernés, et starts_at/ends_at. Les listes sont triées par sévérité puis par mise à jour la plus récente. Les messages commerciaux des opérateurs ne sont pas remontés comme perturbations.

L'enveloppe#

Les réponses réussies sont {"data": …, "meta": {…}}. meta contient toujours generated_at (RFC 3339, UTC) et units (unités facturées). Les listes paginées ajoutent count, limit et next_cursor (null sur la dernière page ; renvoyez-le en cursor). Les endpoints de données ajoutent :

{
  "generated_at": "2026-09-07T12:11:03Z",
  "units": 1,
  "network": "tbm",
  "freshness": "realtime",
  "sources": [
    {"id": "tbm:xtradata:horai", "fetched_at": "2026-09-07T12:10:58Z", "age_seconds": 5, "freshness": "realtime"}
  ],
  "attribution": ["Bordeaux Métropole / TBM — Licence Ouverte 2.0"]
}

Les erreurs sont {"error": {"code": "QVST1-3404", "reason": "stop_not_found", "message": "…", "details": {…}}}. reason et code sont des contrats stables ; message s'adresse aux humains et peut changer. Voir Erreurs.

Unités#

L'usage se compte en unités. Chaque lecture réussie coûte 1 unité, sauf GET /journeys qui en coûte 5, et chaque événement de données poussé sur un stream qui en coûte 1. Les unités sont débitées après une réponse réussie (2xx) ; les erreurs ne coûtent rien. Trois en-têtes accompagnent chaque réponse :

Les mois sont des mois calendaires en UTC. Les limites par minute et le budget mensuel sont décrits dans Limites et tarifs.

Temps et fuseaux horaires#

Toutes les dates sont en RFC 3339 avec le décalage du fuseau du réseau, par exemple 2026-09-07T14:11:03+02:00. meta.generated_at est en UTC. Le paramètre when accepte un instant RFC 3339 (avec décalage) ou le littéral now. Les horaires théoriques après minuit sont rattachés au bon jour de service : une heure GTFS 25:10:00 apparaît comme 01:10:00 le jour calendaire suivant.

En-têtes de cache#

Les réponses portent Cache-Control: private, max-age=<n> où n est le TTL de la source la plus fraîche (10 à 20 secondes en temps réel, 300 pour les données théoriques). Les ressources statiques (réseaux, lignes, arrêts, tracés) portent un ETag ; envoyez If-None-Match pour recevoir 304 Not Modified. Un 304 ne coûte aucune unité.