EN
Aller au contenu

API de transport en commun

Chaque requête nécessite une clé API; voir Authentification.

L'API de données de transport expose la version GTFS statique d'Unmap sous forme d'agences, d'arrêts proches, de lignes et de départs planifiés. Elle utilise la même clé et le même compteur que le routage. Il n'existe ni forfait ni quota distinct pour le transport en commun.

La version est nationale et reconstruite chaque semaine. Elle porte chaque flux que sert le graphe de routage en transport et dont la licence permet la republication: 80 flux dans sept provinces lors de sa première construction nationale, le 2026-10-09, contre huit flux pilotes auparavant. Les flux dont aucun catalogue public ne donne les conditions restent en attente jusqu'à ce qu'on les trouve, et ceux dont les conditions restreignent la redistribution sont écartés. VIA Rail Canada est écarté parce qu'il publie des fréquences (frequencies.txt), qui ne peuvent pas être présentées comme des départs exacts. GET /transit/agencies liste chaque agence de la version servie, et GET /coverage.json explique pourquoi chaque autre flux en est absent. Chaque départ est planifié, pas en temps réel. Quand aucune version n'est disponible, l'API donne un 503 avec retryable: true, donc un compartiment vide ne peut jamais ressembler à un pays sans transport. Voir Couverture pour les flux qui ont franchi les contrôles de licence et de validation.

Client

@unmap/sdk expose les cinq points d'accès sous unmap.transit:

import { Unmap } from "@unmap/sdk";
 
const unmap = new Unmap({ key: "um_live_..." });
 
const agencies = await unmap.transit.agencies();
const stops = await unmap.transit.nearbyStops([-73.5673, 45.5019], {
  radius: 800,
  limit: 10,
});
 
const stop = stops.data[0];
if (stop) {
  const departures = await unmap.transit.departures(stop.id, {
    at: new Date(),
    window: 60,
    limit: 20,
  });
}

Chaque méthode retourne { data, meta }. meta indique la version source, l'attribution et la fraîcheur. Chaque appel de transport statique compte comme un appel normal de routage.

Une réponse peut couvrir plusieurs flux: les arrêts proches à Toronto peuvent venir à la fois de la TTC, de GO Transit, de York Region Transit et de MiWay. meta.sources liste alors chaque flux et meta.attribution réunit leurs mentions d'attribution en une seule chaîne. Affichez cette chaîne partout où vous présentez les données.

Six flux québécois sont publiés sous l'Open Database License (ODbL) 1.0, une licence de partage à l'identique. Leur attribution le dit, et précise que la copie d'unmap est offerte sous l'ODbL 1.0. Si vous redistribuez des données de ces flux, elles restent sous l'ODbL.

Agences

GET /transit/agencies

Retourne toutes les agences de la version activée. Une agence dont l'identifiant GTFS est TTC dans le flux ttc porte l'identifiant um:transit:agency:ttc:TTC. Un flux à agence unique qui omet agency_id utilise la forme du flux, comme um:transit:agency:ttc. Les identifiants GTFS ne sont uniques qu'à l'intérieur d'un flux; un identifiant brut n'est donc jamais présenté comme mondial.

Arrêts proches

GET /transit/stops?near=-73.5673,45.5019&radius=800&limit=10
  • near est obligatoire sous la forme lng,lat en WGS84.
  • radius est exprimé en mètres, de 50 à 10 000. La valeur par défaut est 1 000.
  • limit va de 1 à 100. La valeur par défaut est 20.

Le résultat est filtré selon la distance orthodromique exacte et trié du plus proche au plus lointain. Chaque arrêt porte distance en mètres et un identifiant stable comme um:transit:stop:ttc:1234. Les stations parentes regroupent les lignes et les départs minutés de leurs quais enfants.

Recherche d'un arrêt ou d'une ligne

GET /transit/stops/{id}
GET /transit/routes/{id}

Utilisez l'identifiant Unmap retourné par un autre appel de transport. Encodez-le comme segment de chemin si vous construisez la requête vous-même. Le SDK le fait automatiquement avec getStop(id) et getRoute(id).

Départs

GET /transit/stops/{id}/departures?at=2026-09-17T08:00:00-04:00&window=60&limit=50
  • at est un instant ISO 8601 avec Z ou un décalage explicite. Sa valeur par défaut est maintenant. Une heure locale sans décalage est refusée, car un changement d'heure peut la rendre ambiguë.
  • window va de 1 à 240 minutes. La valeur par défaut est 60.
  • limit va de 1 à 200. La valeur par défaut est 50.

Le compilateur conserve les heures GTFS après minuit et les exceptions de service de calendar_dates.txt. L'API les résout dans le fuseau du flux, y compris aux changements d'heure, et retourne des instants ISO absolus:

{
  "data": [
    {
      "stop_id": "um:transit:stop:ttc:1234",
      "route_id": "um:transit:route:ttc:1",
      "trip_id": "um:transit:trip:ttc:night-1",
      "headsign": "Finch",
      "arrival": "2026-09-18T05:14:00.000Z",
      "departure": "2026-09-18T05:15:00.000Z",
      "stop_sequence": 7,
      "schedule_type": "scheduled"
    }
  ],
  "meta": {
    "source": "Toronto Transit Commission: TTC Routes and Schedules",
    "source_updated_at": null,
    "source_version": "mdb-732",
    "content_hash": "<sha256>",
    "data_version": "20260917-0123456789ab",
    "unmap_updated_at": "2026-09-17T12:00:00.000Z",
    "status": "current",
    "attribution": "Open Government Licence - Toronto",
    "schedule_type": "scheduled"
  }
}

schedule_type vaut toujours scheduled dans cette version, sur chaque ligne et dans meta, même si le résultat est vide. Aucune réponse ne prétend décrire le déplacement d'un véhicule, un retard ou une annulation en direct. GTFS-Realtime appartient à une phase ultérieure et distincte.

Les flux qui utilisent frequencies.txt sont refusés pour l'instant. Un trajet fondé sur une fréquence ne peut pas devenir un départ exact sans inventer une précision que le producteur n'a pas publiée.

Le routage suit un déploiement distinct

L'API statique ne porte que des flux prêts pour le routage sur le graphe de transport: une agence listée ici est une agence que mode=transit peut emprunter. Les deux restent des déploiements distincts: le capabilities.routing de chaque agence ne vaut true que lorsque le graphe de transport est en service. Utilisez mode=transit avec depart_at sur /route et /isochrone seulement lorsque la page de couverture indique que le routage en transport est déployé; un centre d'isochrone sans transport en commun prévu à proximité donne un 422. Il n'existe aucun contrat arrive_by ni de matrice pour le transport en commun.

Prochaines étapes