[FEATURE] Metrolinx API service module

[BreakableHoodie]

Summary

Build a centralised NestJS module for calling the Metrolinx Open Data API. This is a prerequisite for all real-time features: coach check-in (#67), schedule change detection (#163), and service alerts (#187).

Why a shared module

Without it, every contributor implementing a real-time feature has to independently handle:

• API key injection from environment variables
• Server-side response caching (required by Metrolinx ToS §6 — never call per-user-request)
• HTTP client setup and error handling
• Rate limit awareness

Requirements

• API key — read from METROLINX_API_KEY env var; fail loudly on startup if missing when real-time features are enabled
• Caching — all responses cached server-side with appropriate TTLs:
  • Fleet Consist: 1 service day (consists are stable within a day)
  • TripUpdates / Alerts: 30 seconds (feeds refresh on a fixed interval)
  • VehiclePosition: 15 seconds
• Base URL — configurable via env (default: https://api.openmetrolinx.com/OpenDataAPI)
• Format — JSON for structured endpoints, protobuf for GTFS-RT feeds (see [FEATURE] Metrolinx API service module #219 for protobuf setup)
• Error handling — surface API errors clearly; do not silently swallow failures

API key registration

Registration is at https://api.openmetrolinx.com/OpenDataAPI/Help/Registration/en (free, takes up to 10 business days). A key has been requested — coordinate with project maintainers for access.

References

• Full endpoint catalogue: docs/metrolinx-open-data.md
• Caching requirement: Metrolinx API ToS §6, tracked in [FEATURE] Implement server-side caching for Metrolinx real-time API calls #211
• Related: Implement User Check-In API #67, Mechanism to mark itineraries with trips that have a changed schedule #163, [Research Spike] Flesh out the tickets and tasks to incorporate live service interrupts into the app #187, [FEATURE] Implement server-side caching for Metrolinx real-time API calls #211

[BreakableHoodie]

Recommended packages for this module:

npm install @nestjs/cache-manager cache-manager --workspace=backend

@nestjs/cache-manager v3.1.2 (updated April 2026) is the standard NestJS caching layer. It provides CacheModule.registerAsync() for DI-friendly setup and @Inject(CACHE_MANAGER) for injecting the cache into services. In-memory caching is sufficient for MVP (no Redis needed). TTLs can be set per-call:

await cacheManager.set('consist:all', data, 86400); // 1 day TTL
await cacheManager.set('trip-updates', data, 30);    // 30 second TTL

No Metrolinx-specific client library exists on npm or GitHub worth using — every available repo is a hobby project with 0–2 stars. This module needs to be purpose-built, but @nestjs/cache-manager handles the caching requirement cleanly. See also #221 for the protobuf parsing dependency.

API key status: Registration has been submitted via api.openmetrolinx.com. A follow-up email has been sent to OpenData.Program@metrolinx.com to confirm receipt. Approval can take up to 10 business days — coordinate with me (@BreakableHoodie) for access once it arrives.