feat(transit): give live-transit-motis a Transitous instance + prefix routing

live-transit-motis served realtime only from the local MOTIS, yet accepted
mo: (Transitous) ids and queried them against local — so alerts/trip updates
for Transitous-served trips silently failed, and cloud-only deployments got no
realtime at all (no other provider covers Transitous RT).

Align it with transit-motis/geocoding-motis: add a Transitous client and route
by id prefix (mo: -> Transitous, ms:/other -> local), attributing each result
to the matching source. Manifest now mirrors the other two — motis service is
optional (works cloud-only), transitousUrl config, a Transitous healthcheck,
and the transitous data source (with localized strings).

Author: Medformatik

integrations/live-transit-motis/__tests__/index.test.ts

@@ -17,6 +17,14 @@ function createCtx(config: Record<string, unknown> = {}): CtxHandle {
     config,
     manifest: {
       dataSources: [
+        {
+          sourceId: "transitous",
+          name: "Transitous",
+          url: "https://api.transitous.org/",
+          license: "Mixed",
+          providerCountry: "DE",
+          providerPrivacyUrl: "https://transitous.org/privacy/",
+        },
         {
           sourceId: "motis-rt",
           name: "MOTIS GTFS-RT Pass-through",
@@ -70,7 +78,9 @@ describe("live-transit-motis provider", () => {
       alerts: { byStop: true, byRoute: false, byBbox: false },
       tripUpdates: true,
     });
-    expect(provider.attribution[0]?.sourceId).toBe("motis-rt");
+    expect(provider.attribution.map((a) => a.sourceId)).toEqual(
+      expect.arrayContaining(["transitous", "motis-rt"]),
+    );
     expect(typeof provider.getAlertsForStop).toBe("function");
     expect(typeof provider.getTripUpdate).toBe("function");
     expect(provider.getVehiclePositions).toBeUndefined();
@@ -303,4 +313,42 @@ describe("live-transit-motis provider", () => {
       expect(mod.__testing.resolveMotisUrl(ctx)).toBe("http://localhost:8081");
     });
   });
+
+  describe("prefix routing", () => {
+    it("routeForId picks the client + attribution by id prefix", async () => {
+      const mod = await loadModule();
+      const { ctx } = createCtx();
+      mod.setup(ctx);
+      const { routeForId, transitousClient, localClient } = mod.__testing;
+
+      expect(routeForId("mo:NL:123").client).toBe(transitousClient);
+      expect(routeForId("ms:DE:456").client).toBe(localClient);
+      expect(routeForId("8000105").client).toBe(localClient);
+
+      expect(routeForId("mo:x").attribution[0]?.sourceId).toBe("transitous");
+      expect(routeForId("ms:x").attribution[0]?.sourceId).toBe("motis-rt");
+    });
+
+    it("queries Transitous for mo: stops and the local instance for ms: stops", async () => {
+      const motisClient = await import("@motis-project/motis-client");
+      vi.mocked(motisClient.stoptimes).mockResolvedValue({
+        data: { place: { alerts: [] } },
+      } as never);
+
+      const mod = await loadModule();
+      const { ctx, getProvider } = createCtx();
+      mod.setup(ctx);
+      const provider = getProvider();
+
+      await provider.getAlertsForStop?.("mo:NL:123");
+      expect(motisClient.stoptimes).toHaveBeenLastCalledWith(
+        expect.objectContaining({ client: mod.__testing.transitousClient }),
+      );
+
+      await provider.getAlertsForStop?.("ms:DE:456");
+      expect(motisClient.stoptimes).toHaveBeenLastCalledWith(
+        expect.objectContaining({ client: mod.__testing.localClient }),
+      );
+    });
+  });
 });

integrations/live-transit-motis/index.ts

@@ -20,6 +20,7 @@ import { withAttribution } from "@openmapx/mobility-core/result";
 
 const attribution = createManifestAttribution();
 
+import type { Attribution } from "@openmapx/mobility-core/attribution";
 import type { AlertSeverity, ServiceAlert } from "@openmapx/mobility-core/transit";
 
 /**
@@ -30,6 +31,7 @@ import type { AlertSeverity, ServiceAlert } from "@openmapx/mobility-core/transi
  * through every consumer of the local instance.
  */
 const FALLBACK_MOTIS_URL = "http://localhost:8081";
+const TRANSITOUS_URL = "https://api.transitous.org";
 const TIMEOUT_MS = 8_000;
 const PROVIDER_ID = "live-transit-motis";
 const SOURCE_ID = "motis-rt";
@@ -56,18 +58,34 @@ function resolveMotisUrl(ctx: IntegrationContext): string {
 // any multi-value list. Serialise arrays comma-joined to match the spec.
 const QUERY_SERIALIZER = { array: { explode: false, style: "form" } } as const;
 
-const client: Client = (() => {
+function makeClient(baseUrl: string): Client {
   const c = createClient({
-    baseUrl: FALLBACK_MOTIS_URL,
+    baseUrl,
     headers: { "User-Agent": USER_AGENT_TRANSIT },
     querySerializer: QUERY_SERIALIZER,
   });
-  c.interceptors.request.use((request) => {
-    const signal = AbortSignal.timeout(TIMEOUT_MS);
-    return new Request(request, { signal });
-  });
+  c.interceptors.request.use(
+    (request) => new Request(request, { signal: AbortSignal.timeout(TIMEOUT_MS) }),
+  );
   return c;
-})();
+}
+
+// Two instances so realtime is queried against the SAME MOTIS that produced the
+// id: `mo:` ids come from the cloud Transitous instance, everything else (`ms:`)
+// from the deployment's self-hosted MOTIS. Routing by prefix (not reachability)
+// is required — a `mo:` trip simply does not exist in the local instance, and
+// vice versa — and mirrors transit-motis's getVehicleJourney prefix handling.
+const localClient = makeClient(FALLBACK_MOTIS_URL);
+const transitousClient = makeClient(TRANSITOUS_URL);
+
+function routeForId(id: string): { client: Client; attribution: Attribution[] } {
+  if (id.startsWith("mo:")) {
+    const attr = attribution.bySource("transitous");
+    return { client: transitousClient, attribution: attr ? [attr] : [] };
+  }
+  const attr = attribution.bySource("motis-rt");
+  return { client: localClient, attribution: attr ? [attr] : [] };
+}
 
 /** MOTIS id prefixes the local + cloud + RT providers all share. */
 const MOTIS_ID_PREFIX_RE = /^(ms:|mo:|mr:)/;
@@ -184,10 +202,14 @@ function mapMotisAlert(alert: MotisAlert, index: number): ServiceAlert {
 
 export function setup(ctx: IntegrationContext): void {
   attribution.set(ctx.manifest.dataSources ?? []);
-  client.setConfig({
+  localClient.setConfig({
     baseUrl: resolveMotisUrl(ctx),
     headers: { "User-Agent": USER_AGENT_TRANSIT },
   });
+  transitousClient.setConfig({
+    baseUrl: (ctx.config.transitousUrl as string | undefined) || TRANSITOUS_URL,
+    headers: { "User-Agent": USER_AGENT_TRANSIT },
+  });
 
   const provider: RealtimeProvider = {
     id: PROVIDER_ID,
@@ -200,16 +222,17 @@ export function setup(ctx: IntegrationContext): void {
       tripUpdates: true,
     },
     async getAlertsForStop(stopId) {
+      const { client, attribution: attr } = routeForId(stopId);
       try {
         const { data } = await stoptimes({
           client,
           query: { stopId: stripPrefix(stopId), n: 0, window: 0, withAlerts: true },
         });
         const motisAlerts: MotisAlert[] = data?.place?.alerts ?? [];
         const mapped = motisAlerts.map((alert, index) => mapMotisAlert(alert, index));
-        return withAttribution(mapped, attribution.all(), freshnessNow({ hasRealtimeData: true }));
+        return withAttribution(mapped, attr, freshnessNow({ hasRealtimeData: true }));
       } catch {
-        return withAttribution([], attribution.all(), freshnessNow({ hasRealtimeData: true }));
+        return withAttribution([], attr, freshnessNow({ hasRealtimeData: true }));
       }
     },
     async getTripUpdate(tripId, stopId) {
@@ -219,16 +242,17 @@ export function setup(ctx: IntegrationContext): void {
       if (!MOTIS_ID_PREFIX_RE.test(tripId)) {
         return withAttribution(null, attribution.all(), freshnessNow({ hasRealtimeData: true }));
       }
+      const { client, attribution: attr } = routeForId(tripId);
       try {
         const { data } = await motisTrip({
           client,
           query: { tripId: stripPrefix(tripId) },
         });
         const itinerary = data as Itinerary | undefined;
         const delta = itinerary ? deltaFromItinerary(itinerary, tripId, stopId) : null;
-        return withAttribution(delta, attribution.all(), freshnessNow({ hasRealtimeData: true }));
+        return withAttribution(delta, attr, freshnessNow({ hasRealtimeData: true }));
       } catch {
-        return withAttribution(null, attribution.all(), freshnessNow({ hasRealtimeData: true }));
+        return withAttribution(null, attr, freshnessNow({ hasRealtimeData: true }));
       }
     },
   };
@@ -242,5 +266,8 @@ export const __testing = {
   mapMotisAlert,
   mapMotisAlertSeverity,
   resolveMotisUrl,
+  routeForId,
   stripPrefix,
+  localClient,
+  transitousClient,
 };

integrations/live-transit-motis/manifest.json

@@ -6,7 +6,7 @@
   "documentation": "https://motis-project.de/",
   "domains": ["live-transit"],
   "dependencies": ["overlay-live-transit"],
-  "requires": [{ "service": "motis", "optional": false }],
+  "requires": [{ "service": "motis", "optional": true }],
   "backend": {
     "routes": false
   },
@@ -19,15 +19,26 @@
       },
       "endpoint": {
         "type": "string",
-        "title": "MOTIS endpoint",
-        "description": "Base URL of the MOTIS instance. Falls back to the service registry's resolved URL.",
+        "title": "Local MOTIS endpoint URL",
+        "description": "Base URL of a self-hosted MOTIS server. Leave blank to rely on the `motis` service registry entry.",
+        "format": "url"
+      },
+      "transitousUrl": {
+        "type": "string",
+        "title": "Transitous endpoint URL",
+        "description": "Base URL of the cloud Transitous instance, used for realtime on `mo:` (Transitous-served) trips and stops.",
         "format": "url"
       }
     }
   },
   "healthCheck": [
     {
-      "name": "MOTIS endpoint",
+      "name": "Transitous",
+      "type": "http",
+      "url": "https://api.transitous.org/api/v1/geocode?text=test"
+    },
+    {
+      "name": "MOTIS self-hosted",
       "type": "ping",
       "urlTemplate": "${service:motis}",
       "url": "http://localhost:8081"
@@ -36,6 +47,22 @@
   "quality": "built-in",
   "category": "Transit",
   "dataSources": [
+    {
+      "sourceId": "transitous",
+      "name": "Transitous",
+      "url": "https://api.transitous.org/",
+      "license": "Mixed (per upstream GTFS/GBFS feed; mostly open data)",
+      "licenseUrl": "https://transitous.org/sources/",
+      "commercialUse": "conditional",
+      "attribution": "Public transport data via Transitous — see transitous.org/sources/",
+      "notes": "The Transitous public API (api.transitous.org) is 'not intended for commercial or for-profit purposes' — commercial use is decided case-by-case on request, and open-source clients must publish their source and visibly link transitous.org/sources/ for attribution (see transitous.org/api/). The MOTIS routing software is AGPL-3.0-or-later, but that licenses the software, not the data; the aggregated timetable data is per upstream feed (mostly CC-BY / CC-BY-SA / open-government licences).",
+      "providerCountry": "DE",
+      "providerPrivacyUrl": "https://transitous.org/privacy/",
+      "endUserExposure": "server-only",
+      "personalData": false,
+      "cookies": false,
+      "dpaAvailable": false
+    },
     {
       "sourceId": "motis-rt",
       "name": "MOTIS GTFS-RT Pass-through",

integrations/live-transit-motis/strings/de.json

@@ -2,6 +2,11 @@
   "name": "MOTIS GTFS-RT",
   "description": "Live-Meldungen und Fahrplanaktualisierungen von MOTIS",
   "dataSources": {
+    "transitous": {
+      "purpose": "Echtzeit-Verkehrsmeldungen und Fahrplanaktualisierungen für Verbindungen aus dem globalen Transitous-Netz — verwendet, wenn eine Fahrt oder Haltestelle von Transitous stammt (eine `mo:`-ID) und nicht von der selbst gehosteten MOTIS-Instanz",
+      "dataSent": "Eine Haltestellen-ID (für Meldungen) oder Fahrt-ID (für Fahrplanaktualisierungen) für von Transitous bediente Verbindungen wird an api.transitous.org übermittelt; Nutzer- oder Standortdaten werden nicht übermittelt.",
+      "dataReceived": "Verkehrsmeldungen (Titel, Beschreibung, Schweregrad, Auswirkung, Gültigkeitszeiträume) sowie fahrtbezogene Abweichungen (erwartete Zeiten, Verspätung in Sekunden, Gleis, Ausfallstatus)"
+    },
     "motis-rt": {
       "purpose": "Echtzeit-Verkehrsmeldungen und Fahrplanaktualisierungen (Verspätungen, Gleiswechsel, Ausfälle), die aus den von MOTIS eingelesenen GTFS-RT-Feeds durchgereicht werden",
       "dataSent": "Es werden keine Daten an Dritte übermittelt. Die Anfragen gehen an die eigene MOTIS-Instanz von OpenMapX und enthalten lediglich eine interne Haltestellen-ID (für Meldungen) oder Fahrt-ID (für Fahrplanaktualisierungen); Nutzer- oder Standortdaten werden nicht übermittelt.",

integrations/live-transit-motis/strings/en.json

@@ -2,6 +2,11 @@
   "name": "MOTIS GTFS-RT",
   "description": "Live alerts and trip updates from MOTIS",
   "dataSources": {
+    "transitous": {
+      "purpose": "Realtime service alerts and trip updates for journeys served by the global Transitous network — used when a trip or stop comes from Transitous (a `mo:` id) rather than the self-hosted MOTIS instance",
+      "dataSent": "A stop ID (for alerts) or trip ID (for trip updates) for Transitous-served journeys is sent to api.transitous.org; no user or location data is included.",
+      "dataReceived": "Service alerts (title, description, severity, effect, validity periods) and trip-level deltas (expected times, delay in seconds, platform, cancellation status)"
+    },
     "motis-rt": {
       "purpose": "Realtime service alerts and trip updates (delays, platform changes, cancellations) passed through from GTFS-RT feeds ingested by MOTIS",
       "dataSent": "Nothing is sent to a third party. Requests go to OpenMapX's own MOTIS deployment and carry only an internal stop ID (for alerts) or trip ID (for trip updates); no user or location data is included.",