feat(roads): ingest Barcelona TRAMS real-time traffic status

Add the Barcelona "estat del trànsit" TRAMS feed (Ajuntament de Barcelona,
CC-BY-4.0, no auth): a `#`-delimited live status file on a 0-6 congestion
scale, with per-segment polyline geometry joined by tram id from a companion
long-format CSV dictionary via a new "bcn-trams-csv" station registry.
Categorical status only (no measured speed); level-of-service and derived
congestion events come from the shared flow builder. New "bcn-trams" flow
format + parser.

Author: Medformatik

packages/core/src/model.ts

@@ -50,6 +50,7 @@ export type SourceFormat =
   | "fdt"
   | "hk-td"
   | "geojson-flow"
+  | "bcn-trams"
   | "gtfs-rt"
   | "native"
   | "crowd";

packages/roads/feeds/roads/es.json5

@@ -26,4 +26,28 @@
     country: "ES",
     privacyUrl: "https://www.madrid.es/portal/site/munimadrid/menuitem.privacy",
   },
+  {
+    subdivision: "bcn",
+    operator: "ajuntament",
+    name: "Estat del trànsit TRAMS (Barcelona)",
+    format: "bcn-trams",
+    produces: "flow",
+    // Live status file: one `#`-delimited row per segment
+    // (tramId#YYYYMMDDHHMMSS#estatActual#estatPrevist15min) on a 0-6 congestion
+    // scale. Categorical only (no speed). The segment geometry lives in a
+    // separate long-format CSV dictionary, joined by tram id via the station
+    // registry below.
+    url: "https://opendata-ajuntament.barcelona.cat/data/dataset/8319c2b1-4c21-4962-9acd-6db4c5ff1148/resource/2d456eb5-4ea6-4f68-9794-2f3f1a58a933/download",
+    stationRegistry: {
+      url: "https://opendata-ajuntament.barcelona.cat/data/dataset/0e3b6840-7dff-4731-a556-44fac28a7873/resource/c97072a3-3619-4547-84dd-f1999d2a3fec/download/transit_relacio_trams_format_long.csv",
+      format: "bcn-trams-csv",
+    },
+    cadenceSec: 300,
+    freshnessWindowSec: 900,
+    license: "CC-BY-4.0",
+    licenseUrl: "https://creativecommons.org/licenses/by/4.0/",
+    attribution: "Ajuntament de Barcelona",
+    country: "ES",
+    privacyUrl: "https://www.barcelona.cat/en/privacy-policy",
+  },
 ]

packages/roads/src/__tests__/feeds.test.ts

@@ -421,8 +421,8 @@ describe("FEED_SOURCES", () => {
     expect(new Set(ids).size).toBe(ids.length);
   });
 
-  it("loads every feed from the data files (all 72 migrated)", () => {
-    expect(FEED_SOURCES.length).toBe(72);
+  it("loads every feed from the data files (all 73 migrated)", () => {
+    expect(FEED_SOURCES.length).toBe(73);
     expect(new Set(FEED_SOURCES.map((f) => f.id)).size).toBe(FEED_SOURCES.length);
   });
 

packages/roads/src/__tests__/flow-bcn.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { parseBcnTramsFlow } from "../flow-bcn.js";
+import { parseBcnTramsStations } from "../stations-bcn.js";
+import type { SiteGeometry } from "../siteTable.js";
+import type { SourceDescriptor } from "../types.js";
+
+const src = {
+  id: "es-bcn-ajuntament",
+  attribution: "Ajuntament de Barcelona",
+  country: "ES",
+  license: "CC-BY-4.0",
+} as SourceDescriptor;
+
+const CSV = `Tram,Tram_Components,Descripció,Longitud,Latitud
+1,1,"Diagonal (Ronda de Dalt a Doctor Marañón)",2.11203535639414,41.3841912394771
+1,2,"Diagonal (Ronda de Dalt a Doctor Marañón)",2.101502862881051,41.3816307921222
+2,1,"Meridiana",2.18,41.42
+2,2,"Meridiana",2.19,41.43
+9,1,"Single vertex only",2.0,41.0`;
+
+describe("parseBcnTramsStations", () => {
+  it("groups vertices per tram (ordered) into LineStrings and drops single-vertex trams", () => {
+    const map = parseBcnTramsStations(CSV);
+    expect(map.size).toBe(2); // tram 9 has one vertex → dropped
+    const geom = map.get("1") as Extract<SiteGeometry, { type: "LineString" }>;
+    expect(geom.type).toBe("LineString");
+    expect(geom.coordinates).toEqual([
+      [2.11203535639414, 41.3841912394771],
+      [2.101502862881051, 41.3816307921222],
+    ]);
+  });
+});
+
+describe("parseBcnTramsFlow", () => {
+  const siteMap = parseBcnTramsStations(CSV);
+
+  it("joins status rows to geometry and maps the 0-6 scale to level-of-service", () => {
+    const dat = ["1#20260729131557#2#2", "2#20260729131557#5#5"].join("\n");
+    const { flows, events } = parseBcnTramsFlow(dat, src, siteMap);
+    expect(flows).toHaveLength(2);
+    const t1 = flows.find((f) => f.id === "es-bcn-ajuntament:1")!;
+    expect(t1.los).toBe("free_flow");
+    expect(t1.speedKph).toBeUndefined();
+    expect(t1.geometry.type).toBe("LineString");
+    expect(t1.dataUpdatedAt).toBe("2026-07-29T13:15:57");
+    const t2 = flows.find((f) => f.id === "es-bcn-ajuntament:2")!;
+    expect(t2.los).toBe("stationary");
+    expect(t2.sourceFormat).toBe("bcn-trams");
+    // Only the congested (stationary) segment yields a derived congestion event.
+    expect(events).toHaveLength(1);
+    expect(events[0]!.type).toBe("congestion");
+  });
+
+  it("skips status 0 (sensor down) and segments with no known geometry", () => {
+    const dat = ["1#20260729131557#0#0", "999#20260729131557#3#3"].join("\n");
+    const { flows } = parseBcnTramsFlow(dat, src, siteMap);
+    expect(flows).toHaveLength(0);
+  });
+
+  it("flags a hard parse failure on an empty/garbage body", () => {
+    expect(parseBcnTramsFlow("", src, siteMap).failed).toBe(true);
+    expect(parseBcnTramsFlow("<html>error</html>", src, siteMap).failed).toBe(true);
+  });
+});

packages/roads/src/feed-schema.ts

@@ -86,6 +86,7 @@ export const roadFeedSchema = z
           "miv-config",
           "france-comptage-csv",
           "hk-detector-csv",
+          "bcn-trams-csv",
         ]),
       })
       .strict()

packages/roads/src/feeds.ts

@@ -32,6 +32,7 @@ import { parseMivFlow } from "./miv.js";
 import { parseTurinFlow } from "./flow-turin.js";
 import { parseHkRawFlow } from "./hk.js";
 import { parseGeojsonFlow } from "./flow-geojson.js";
+import { parseBcnTramsFlow } from "./flow-bcn.js";
 import type { GeojsonFlowMapping, SourceDescriptor } from "./types.js";
 
 // FeedAuth now lives in @openconditions/ingest-framework; re-exported here so
@@ -76,7 +77,8 @@ export type FeedSource = FeedSourceBase & {
       | "webtris-sites"
       | "miv-config"
       | "france-comptage-csv"
-      | "hk-detector-csv";
+      | "hk-detector-csv"
+      | "bcn-trams-csv";
   };
   /** Field mapping for `format: "geojson"` feeds (passed to the generic reader). */
   geojson?: GeoJsonMapping;
@@ -176,6 +178,7 @@ export function flowParserFor(format: SourceFormat): FlowParserFn {
   if (format === "fdt") return parseTurinFlow;
   if (format === "hk-td") return parseHkRawFlow;
   if (format === "geojson-flow") return parseGeojsonFlow;
+  if (format === "bcn-trams") return parseBcnTramsFlow;
   throw new Error(`No flow parser registered for format: ${format}`);
 }
 

packages/roads/src/flow-bcn.ts

@@ -0,0 +1,79 @@
+import type { RoadEvent, RoadFlow } from "./model.js";
+import type { SourceDescriptor } from "./types.js";
+import type { SiteGeometry } from "./siteTable.js";
+import { buildMeasuredSiteFlow, makeOrigin } from "./flow.js";
+import type { FlowParseResult } from "./flow.js";
+
+/**
+ * Barcelona's 0-6 congestion scale → DATEX status tokens the shared flow builder
+ * derives level-of-service from. 0 = sensor down (no data) → skipped entirely.
+ */
+const STATUS_TO_DATEX: Record<string, string> = {
+  "1": "freeFlow", // molt fluid
+  "2": "freeFlow", // fluid
+  "3": "heavy", // dens
+  "4": "congested", // molt dens
+  "5": "stationary", // congestió
+  "6": "blocked", // tallat
+};
+
+/** "YYYYMMDDHHMMSS" → ISO-8601 local timestamp, or undefined when malformed. */
+function parseBcnTimestamp(raw: string): string | undefined {
+  const m = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/.exec(raw);
+  if (!m) return undefined;
+  const [, y, mo, d, h, mi, s] = m;
+  return `${y}-${mo}-${d}T${h}:${mi}:${s}`;
+}
+
+/**
+ * Parse Barcelona's live "estat del trànsit" TRAMS feed — one `#`-delimited row
+ * per segment: `tramId#YYYYMMDDHHMMSS#estatActual#estatPrevist15min`, the status
+ * a 0-6 congestion scale. Geometry comes from the injected TRAMS registry
+ * (tram id → LineString). Categorical status only (no speed); segments with
+ * status 0 (sensor down) or no resolvable geometry are skipped. los and the
+ * derived congestion events come from the shared {@link buildMeasuredSiteFlow};
+ * only the sourceFormat is restamped here.
+ */
+export function parseBcnTramsFlow(
+  input: string | Buffer,
+  src: SourceDescriptor,
+  siteMap?: Map<string, SiteGeometry>
+): FlowParseResult {
+  const text = Buffer.isBuffer(input) ? input.toString("utf8") : input;
+  if (typeof text !== "string" || text.trim() === "") {
+    return { flows: [], events: [], failed: true };
+  }
+
+  const flows: RoadFlow[] = [];
+  const events: RoadEvent[] = [];
+  const now = new Date().toISOString();
+  const origin = makeOrigin(src);
+  let sawRow = false;
+
+  for (const line of text.split(/\r?\n/)) {
+    const parts = line.split("#");
+    if (parts.length < 3) continue;
+    const [tramId, ts, status] = parts;
+    if (!tramId) continue;
+    sawRow = true;
+    const geom = siteMap?.get(tramId.trim());
+    if (!geom) continue;
+    const trafficStatus = status != null ? STATUS_TO_DATEX[status.trim()] : undefined;
+    if (!trafficStatus) continue; // status 0 (no data) or unrecognised value
+    const measuredAt = (ts ? parseBcnTimestamp(ts.trim()) : undefined) ?? now;
+    const built = buildMeasuredSiteFlow(
+      { siteId: tramId.trim(), measuredAt, geom, trafficStatus },
+      src,
+      origin,
+      now
+    );
+    if (!built) continue;
+    flows.push({ ...built.flow, sourceFormat: "bcn-trams" });
+    if (built.event) events.push({ ...built.event, sourceFormat: "bcn-trams" });
+  }
+
+  // A body that parsed to zero recognizable rows is a hard failure (error page),
+  // not a legitimately empty cycle — every real fetch carries ~530 segments.
+  if (!sawRow) return { flows: [], events: [], failed: true };
+  return { flows, events };
+}

packages/roads/src/index.ts

@@ -25,6 +25,7 @@ export * from "./predefined-locations.js";
 export * from "./stations-fintraffic.js";
 export * from "./stations-webtris.js";
 export * from "./stations-france.js";
+export * from "./stations-bcn.js";
 export * from "./miv.js";
 export * from "./flow-turin.js";
 export * from "./hk.js";

packages/roads/src/stations-bcn.ts

@@ -0,0 +1,31 @@
+import type { LineString } from "geojson";
+import type { SiteGeometry } from "./siteTable.js";
+
+/**
+ * Parse Barcelona's "Relació de trams" long-format CSV
+ * (`Tram,Tram_Components,Descripció,Longitud,Latitud`) into a tram-id →
+ * LineString registry for the TRAMS flow parser. One row per polyline vertex;
+ * vertices are ordered by `Tram_Components`. The quoted `Descripció` column
+ * (which itself contains commas) is skipped by anchoring the match on the two
+ * leading integer columns and the two trailing coordinate columns.
+ */
+export function parseBcnTramsStations(input: string): Map<string, SiteGeometry> {
+  const byTram = new Map<string, { seq: number; lon: number; lat: number }[]>();
+  const rowRe = /^(\d+),(\d+),.*,(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)\s*$/;
+  for (const line of input.split(/\r?\n/)) {
+    const m = rowRe.exec(line);
+    if (!m) continue;
+    const [, tram, seq, lon, lat] = m;
+    const arr = byTram.get(tram!) ?? [];
+    arr.push({ seq: Number(seq), lon: Number(lon), lat: Number(lat) });
+    byTram.set(tram!, arr);
+  }
+  const map = new Map<string, SiteGeometry>();
+  for (const [tram, pts] of byTram) {
+    if (pts.length < 2) continue;
+    pts.sort((a, b) => a.seq - b.seq);
+    const coordinates = pts.map((p) => [p.lon, p.lat] as [number, number]);
+    map.set(tram, { type: "LineString", coordinates } satisfies LineString);
+  }
+  return map;
+}

services/ingest/src/pipeline/station-registry.ts

@@ -1,5 +1,6 @@
 import type { FeedSource, SiteGeometry } from "@openconditions/roads";
 import {
+  parseBcnTramsStations,
   parseFintrafficStations,
   parseFranceComptageStations,
   parseHkDetectors,
@@ -28,6 +29,7 @@ const PARSERS: Record<string, (input: string) => Map<string, SiteGeometry>> = {
   "miv-config": parseMivConfig,
   "france-comptage-csv": parseFranceComptageStations,
   "hk-detector-csv": parseHkDetectors,
+  "bcn-trams-csv": parseBcnTramsStations,
 };
 
 /**