Transit
Live departures, vehicle positions, and service alerts from GTFS-RT feeds.
Parchment reads the same real-time feeds agencies publish for their own apps. Where an agency publishes GTFS-RT, departures carry live predictions rather than the timetable, vehicles move on the map, and anything the agency has said about a disruption is shown alongside them.
All of it comes through Barrelman, which discovers each feed's real-time URLs from Transitland during the GTFS import and stores them on the feed.
Service alerts
A service alert is the agency's own word on a disruption — a detour around roadworks, a suspended line, a lift out of service. Parchment reads the GTFS-RT ServiceAlerts feed and shows each alert wherever it applies:
| Where | What you see |
|---|---|
| Route page | Every alert on that line, worst first, under "Alerts on this line" |
| Stop departure board | Alerts naming the stop, plus a badge on each line that has one |
| Planned trip | The alerts for each transit leg, above that leg's departure board |
| Departure chip | A badge on a run the agency has published something about |
Alerts already in effect lead; anything whose window opens later is filed under "Upcoming alerts", so next weekend's planned closure doesn't sit above tonight's suspension. Where the feed says an alert is planned work rather than a live incident, it is drawn one step quieter — a scheduled closure warns, an unplanned one is red.
Severity
Agencies are inconsistent about setting a severity on an alert, so Parchment falls back to the alert's effect when they leave it unset — a suspension with no severity is still drawn as a suspension, not as a footnote.
| Drawn as | When |
|---|---|
| Red | Severity SEVERE, or effect NO_SERVICE |
| Amber | Severity WARNING, or effects like DETOUR, SIGNIFICANT_DELAYS, REDUCED_SERVICE, STOP_MOVED |
| Muted | Everything else |
Agency prose runs long — stop lists, notes about arrival predictions — so anything past a few lines is collapsed behind "Show more".
Agencies that don't fill in the spec fields
Some agencies leave cause, effect and severity_level unset on every alert and publish the real category in a vendor extension instead. The MTA is one: all of its alerts arrive as UNKNOWN_EFFECT / UNKNOWN_SEVERITY, with the category — "Planned - Detour", "Planned - Suspended", "Delays" — in a MercuryAlert extension the standard GTFS-RT decoders drop.
Barrelman reads those extensions, so an MTA detour is drawn as a detour rather than as an unlabelled grey note. The extension also carries the time the agency published the alert, which is what the card's "Posted" line shows.
Support is a registry (src/services/alert-extensions.ts in Barrelman): each agency's extension is one entry giving the protobuf field number it occupies and a function that reads it. Adding another agency's format needs no change to the alerts service, and an alert's own spec fields always win — an extension only fills a gap the feed left.
What an agency has to publish
Alerts need a GTFS-RT ServiceAlerts feed. Barrelman finds it through Transitland, alongside the trip update and vehicle position feeds.
Discovery goes through the operator, not the feed id. An agency's realtime feeds are separate records from its static one and are not named after it — MTA New York City Transit's static subway feed is f-dr5r-nyctsubway while its realtime feeds are f-mta~nyc~rt~subway~a~c~e and nine others. Asking which operator runs a feed, then taking that operator's GTFS-RT feeds, finds all of them; deriving an id from the static feed finds none. Each URL's kind is recorded when it is discovered, because one agency's feeds cover several modes and the URL alone doesn't say which is which.
An agency that publishes no alerts feed simply shows no alerts — nothing else about its departures or vehicles changes.
If a region's real-time URLs were never discovered, run the discovery pass on Barrelman:
curl -X POST http://localhost:5001/transit/discover-rt-urls \
-H 'Content-Type: application/json' \
-d '{}'Pass {"feedId": "..."} to limit it to one feed. Discovery needs a Transitland API key in Barrelman's environment.
Freshness
Barrelman caches each feed's alerts for a minute, and Parchment caches an answer for a minute on top of that. An alert an agency posts mid-journey reaches an open trip within about two minutes; opening a route or stop page fetches on entry.