RouteReality v2.0.0

RouteReality v2.0 Release Notes

Release Date: April 2026
Status: Major update – Community & Real-Time Features

This release marks the transition to Version 2.0, introducing authentication, user engagement mechanics, real-time capabilities, and a significantly improved prediction engine.

All changes since V1.3.0 (February 21, 2026) have been consolidated here.

Added (New V2 Features)

• JWT Authentication
  Protected routes for journey creation, event submission, and user-specific data. Public read-only endpoints remain open.

• User Stats & Leaderboard

  • Personal contribution tracking (points, journeys, events submitted, rank)
  • Community leaderboard (all-time and weekly) with badges (Hot Streak, Early Reporter, Reliable Source)
  • Points system: ARRIVED (10 pts), DELAYED (15 pts), STOP_REACHED (20 pts) + daily bonuses

• Stop-Based Arrivals
  New endpoint: GET /arrivals/stop/{stop_id} — view all upcoming buses/trams at any stop.

• Web Push Notifications
  Full server-side support using VAPID keys.
  Added gen_vapid.py script for easy key generation and expiration handling.

• WebSocket Broadcasting
  Live real-time updates when journey status changes (with sync context fixes).

• Improved Prediction Engine (Prediction V2)

  • Time-sensitive weighted average with better handling of recency, traffic patterns, and time-of-day effects.
  • Enhanced arrival reporting loop.
  • Richer prediction payload including source, recent_event_count, and historical_count.

• Three UI screenshots added to README (Home / start journey map, route view with event reporting, active journey screen).

• JourneyEventType.PENDING for clearer initial journey states.

• Structured logging throughout prediction and event handling.

• recent_trips limit and counts in status endpoints.

• Server-side push support and VAPID key generation.

Changed

• Prediction interface: renamed static_dt → reference_time, improved fallback safety.
• Centralized prediction refresh with new update_prediction helper.
• Tightened event state transitions and validation.
• Adjusted predicted_arrival handling on DELAYED events.
• Removed unnecessary .isoformat() conversions in API responses.
• CIF timetable path now loaded from environment variable.
• Consistent 3-tuple return from get_closest_scheduled_time_to_now.
• Updated timetable data for March 2026 service changes.
• Improved internal service boundaries for easier maintenance.
• Updated requirements and dependencies (including psycopg3-binary).

Fixed

• Safe unpacking of timetable results with proper type hints.
• Edge cases causing negative ETAs after live overrides.
• Prediction failures now logged gracefully instead of crashing.
• Resource validation (route/stops) with explicit 404/400 status codes.
• Various minor bugs across services and API routes.
• Type annotations and schema consistency.
• WebSocket broadcast issues from sync context.

Improved

• Confidence scoring accuracy under low-data conditions.
• Debuggability with better logging at key decision points.
• Overall system stability and predictability.
• User schema types and requirements handling.

RouteReality V1.3

[1.3.0] - 2026-02-21 – Stability & Cleanup Release

Added

• Three UI screenshots to README (start journey map, event reporting, active journey screen)
• JourneyEventType.PENDING to support clearer initial journey states
• Structured logging throughout prediction and event handling
• Richer prediction payload: source, recent_event_count, historical_count
• recent_trips limit and counts in status endpoints

Changed

• Prediction interface: renamed static_dt → reference_time, improved fallback safety
• Centralized prediction refresh with new update_prediction helper
• Tightened event state transitions and validation
• Adjusted predicted_arrival handling on DELAYED events
• Removed unnecessary .isoformat() conversions in API responses
• CIF timetable path now loaded from environment variable
• Consistent 3-tuple return from get_closest_scheduled_time_to_now

Fixed

• Safe unpacking of timetable results with proper type hints
• Edge cases causing negative ETAs after live overrides
• Prediction failures now logged gracefully instead of crashing
• Resource validation (route/stops) with explicit 404/400 status codes
• Various minor bugs across services and API routes
• Type annotations and schema consistency

Improved

• Confidence scoring accuracy under low-data conditions
• Internal service boundaries for easier future maintenance
• Debuggability with better logging at key decision points
• Overall system stability and predictability

This release focuses purely on hardening the existing system. It lays solid groundwork for v2 features (authentication, real-time updates, richer modelling).

RouteReality V1.2

v1.2 — Backend Updates and map support, Feb 14, 2026

Added

• Users can now properly report "bus arrived" / "bus departed" — server takes it seriously
• New endpoint returns latest confirmed event for route
• Reported events now instantly update route/stop status for everyone else
• Prediction no longer tells people the bus is coming in -2 min after someone already said it left
• Frontend auto-polls every 20s when you're staring at a route/stop — feels almost live
• If timetable is already missed and someone reports departure → we push the next bus forward instead of lying

Fixed

• No more negative arrival times after a departure report
• Less "bus coming in 0 min" when timetable is stale and no live data

Limitations

• Accuracy is only good if enough people bother reporting
• No push notifications yet — still gotta stare at the screen and wait for poll
• Prediction still rough when no recent reports and timetable is way off

Keep reporting — the more people use it, the less stupid the ETAs become.

RouteReality V1.1

V1.1 - 08-02-2026

Added

• Weighted averaging of recent journey data
• Confidence scoring for arrival predictions
• Clear distinction between predicted times and user-reported events/times in the UI

Changed

• Predition logic now prioritises revent user data over static timetables
• Improved fallback behaviour when user data is sparse or unavailable

Fixed

• Improved handling edge cases where no recent journey data exists
• Improved creating journey process
• Better error handling in terms of invalid data

RouteReality V1.0

v0.1.0 "Bootstrap" - January 2026

Initial Release

First public release of RouteReality , a crowdsourced journey tracking and prediction system for public transit.

Features

Journey Tracking

• Start and track active bus journeys
• Submit real-time journey events (arrived, delayed, stop reached)
• Complete journey lifecycle management with state validation

Smart Predictions

• Tiered prediction engine that improves with data volume
• 20+ user journeys: Uses only real user data
• 5-19 journeys: Blends user data with official timetables
• <5 journeys: Falls back to official schedules
• Statistical analysis using median (robust to outliers) with 5+ data points

API Endpoints

• GET /route/routes - List all available routes
• GET /route/routes/{route_id}/stops - Get stops for a route
• POST /journeys/start - Create new journey with predictions
• POST /journeys/{journey_id}/event - Update journey status

Data Model

• Support for multiple routes and stops
• Journey state machine (STARTED → DELAYED → ARRIVED → STOP_REACHED)
• Track both user-submitted and official timetable data
• Store predictions for accuracy tracking

Technical Details

• Built with FastAPI and SQLAlchemy
• PostgreSQL database with proper indexing
• RESTful API with OpenAPI documentation
• UTC timezone handling throughout
• Comprehensive logging for debugging and monitoring

Known Limitations

• No authentication or authorization
• No time-of-day or day-of-week patterns in predictions
• No real-time journey updates (polling only)
• Limited to completed journey predictions
• No data cleanup for old journeys

Requirements

• Python 3.9+
• PostgreSQL
• See requirements.txt for full dependency list

Documentation

• Quick start guide in README.md
• Full technical documentation in TECHNICAL_DOCUMENTATION.md
• API documentation at /docs endpoint

What's Next (v0.2.0)

• User authentication and personal journey history
• Time-based prediction patterns (rush hour awareness)
• WebSocket support for real-time updates
• Data quality improvements and outlier filtering
• Expanded test coverage

---

Contributors Welcome! Check out CONTRIBUTING.md for areas where we need help.

Feedback? Open an issue or submit a PR. We're especially interested in:

• Prediction algorithm improvements
• Real-world usage feedback
• Transit agency integrations
• Performance optimizations

Full Changelog: https://github.com/dillionhuston/bus-tracker-api/commits/RouteRealityv0.10Beta