Project: expand mta-js beyond NYC transit feeds

[gtokman]

Goal

Expand mta-js from an NYC/MTA-focused client into a small multi-agency urban rail/transit client, while preserving the current MTA API surface and Bun-first development workflow.

Why this matters

The repo already has a reusable GTFS-Realtime decoder and a hosted/static lookup model. Many US subway, metro, light rail, and rapid transit agencies expose GTFS static data, GTFS-Realtime protobuf feeds, or public REST APIs. We can add agencies incrementally by starting with agencies whose public feeds map cleanly to the existing arrivals, vehicles, alerts, stops.near, and route metadata concepts.

Implementation shape to investigate

• Add an agency/provider layer instead of hardcoding every feed into MTA-specific config.
• Keep MTA as a backwards-compatible export; consider a broader Transit or AgencyClient export for non-NYC systems.
• Normalize shared outputs for arrivals, vehicle positions, alerts, routes, stops, and colors.
• Support per-agency auth/config: API key headers, query params, no-auth GTFS-RT URLs, and hosted proxy endpoints.
• Add fixtures for static GTFS zips and GTFS-RT protobuf responses so bun test can cover each adapter without live network calls.
• Prioritize agencies with GTFS-RT first because src/gtfs-realtime.ts already decodes protobuf feeds.

Priority 1: requested systems

BART

• Official developer docs: https://www.bart.gov/schedules/developers/api
• GTFS/static data: https://www.bart.gov/schedules/developers/gtfs
• Notes: BART exposes a legacy REST/XML API plus GTFS static and GTFS-Realtime resources. Good first non-MTA rail-only adapter because the network is compact and route/station concepts are clean.
• Work to verify: realtime feed coverage for trip updates, service alerts, and vehicle positions; API key requirements for legacy endpoints.

Muni / SFMTA

• 511 SF Bay open transit data: https://511.org/open-data/transit
• 511 Transit API docs: https://511.org/open-data/token
• SFMTA developer resources: https://www.sfmta.com/getting-around/muni/routes-stops/developer-resources
• Notes: Muni data is usually consumed through 511 regional GTFS and GTFS-Realtime feeds. This is broader than subway because Muni includes light rail, bus, cable car, and historic streetcar.
• Work to verify: feed URLs by operator, token requirements, rate limits, and agency IDs for Muni-only filtering.

MBTA

• MBTA V3 API docs: https://api-v3.mbta.com/docs/swagger/index.html
• MBTA developer portal: https://www.mbta.com/developers/v3-api
• GTFS and realtime feeds: https://www.mbta.com/developers/gtfs
• Notes: Very strong candidate. V3 API exposes predictions, vehicles, alerts, routes, stops, schedules, and facilities using JSON:API. Also has GTFS static and realtime feeds.
• Work to verify: whether to use V3 JSON for richer typed SDK ergonomics, GTFS-RT for shared parser coverage, or both.

Washington, DC / WMATA

• WMATA developer portal: https://developer.wmata.com/
• Rail prediction API: https://developer.wmata.com/docs/services/5476364f031f590f38092507/operations/5476364f031f5909e4fe3311
• GTFS: https://developer.wmata.com/docs/services/gtfs
• Notes: WMATA has rail-specific APIs for stations, lines, incidents, and next trains, plus GTFS resources. API key required.
• Work to verify: best mapping from WMATA Line, Station, and Min fields into normalized arrivals.

Los Angeles Metro

• LA Metro developer portal: https://developer.metro.net/
• Realtime API docs: https://developer.metro.net/api/
• GTFS-Realtime reference: https://developer.metro.net/api/realtime-api/
• Notes: Metro publishes GTFS static and GTFS-Realtime feeds for trip updates, vehicle positions, and alerts. Includes heavy rail and light rail.
• Work to verify: route IDs for A/B/C/D/E/K lines and whether API v2 JSON endpoints should supplement GTFS-RT.

MARTA

• Developer resources: https://www.itsmarta.com/app-developer-resources.aspx
• Notes: MARTA publishes GTFS static data and public realtime resources. Small rail network, useful as an adapter test case after BART.
• Work to verify: current rail realtime endpoint format, API key requirements, and whether bus/rail share the same API response schema.

SEPTA

• Developer portal: https://www3.septa.org/developer/
• TransitView and TrainView APIs: https://www3.septa.org/api/
• Notes: SEPTA has public APIs plus GTFS resources. Coverage spans subway/elevated, trolley, bus, and regional rail, so adapter scope should start with rapid transit and expand carefully.
• Work to verify: realtime subway/trolley support versus regional rail-specific APIs; consistent stop and route IDs across GTFS and API responses.

Priority 2: good additional candidates

CTA / Chicago L

• Train Tracker API docs: https://www.transitchicago.com/developers/traintracker/
• CTA developer resources: https://www.transitchicago.com/developers/
• Notes: High-value addition: rail-specific API, mature documentation, real subway/elevated use case. API key required.

PATH

• PATH schedules and GTFS: https://www.panynj.gov/path/en/schedules-maps/gtfs.html
• Notes: Good NYC-area complement. Confirm whether realtime GTFS-RT is public and how alerts are published before committing beyond static support.

NJ Transit

• Developer tools: https://www.njtransit.com/developer-tools
• Notes: Useful regional complement, though it is not a subway system. Evaluate public GTFS/GTFS-RT coverage and auth terms.

Miami-Dade Metrorail / Metromover

• Transit Tracker services: https://www.miamidade.gov/transit/WebServices/TransitTracker/
• Open data portal: https://gis-mdc.opendata.arcgis.com/
• Notes: Metrorail and Metromover are a good urban-rail target. Validate stable GTFS/GTFS-RT endpoints and API response licensing.

TriMet MAX / Portland

• Developer portal: https://developer.trimet.org/
• Notes: Public API with app ID, arrivals, vehicles, routes, and GTFS. Strong candidate for proving configurable auth/query-param support.

Sound Transit Link / Seattle

• Open transit data: https://www.soundtransit.org/help-contacts/business-information/open-transit-data-otd
• Notes: Good light-rail candidate. Evaluate GTFS-RT availability and whether King County Metro regional feeds are needed for complete coverage.

Denver RTD rail

• Open records / GTFS resources: https://www.rtd-denver.com/open-records/open-spatial-data
• Notes: Candidate for static plus realtime research; verify current public API story before implementation.

Dallas DART rail

• Open data: https://www.dart.org/about/planning-and-development/dart-open-data
• Notes: Candidate for GTFS static and potentially realtime. Verify feed availability and licensing.

Shared references

• GTFS Schedule docs: https://gtfs.org/schedule/
• GTFS-Realtime reference: https://gtfs.org/documentation/realtime/reference/
• GTFS-Realtime best practices: https://gtfs.org/documentation/realtime/realtime-best-practices/

Proposed milestones

1. Research spike: confirm feed URLs, auth, licensing, realtime entity coverage, and update cadence for each Priority 1 agency.
2. Adapter design: introduce provider config, normalized route/stop/arrival/vehicle/alert types, and backwards-compatible MTA exports.
3. First adapter: BART or MBTA, chosen based on easiest live feed + static fixture setup.
4. Bay Area adapter: add Muni/SFMTA via 511 after token handling and operator filtering are clear.
5. Northeast/large systems: MBTA, WMATA, SEPTA, CTA.
6. West/South systems: LA Metro, MARTA, Miami-Dade, TriMet, Sound Transit, DART, Denver RTD as verified.
7. Docs/examples: show per-agency setup, required API keys, feed limitations, and normalized output examples.

Acceptance criteria

• Existing MTA tests and public exports continue to pass.
• Each added agency has documented feed URLs, auth requirements, and source links.
• Each adapter has offline fixtures and bun test coverage for at least arrivals and alerts where data is available.
• Agency-specific quirks are documented instead of hidden in generic code paths.
• README includes a clear support matrix for static GTFS, trip updates, vehicle positions, alerts, auth, and known limitations.