API de transport en commun

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.

Le contrat existe, mais aucune version de production n'est encore activée. Chaque point d'accès de cette page donne un 503 avec retryable: true jusqu'à ce que TRANSIT_DATA_VERSION désigne une version immuable et validée. 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.

@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.

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.

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.

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).

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

Les données statiques et le routage ont des barrières de livraison distinctes. Une agence peut apparaître ici avant que son flux puisse être inclus sans risque dans Valhalla. Utilisez mode=transit avec depart_at sur /route seulement lorsque la page de couverture indique que le routage en transport est déployé. Il n'existe aucun contrat arrive_by, de matrice ou d'isochrone pour le transport en commun.