Viewing Schedules

Access bus schedules and upcoming departure times for all 7 university bus routes

The MND system provides real-time access to bus schedules, allowing students to check when the next bus will arrive at their stop.

Available Bus Routes

MND tracks 7 university bus routes operating between various locations in Sylhet and SUST campus.

Get All Routes

Retrieve a list of all available bus routes:

curl http://localhost:3000/api/routes/list

Response Example

{
  "count": 7,
  "routes": [
    {
      "route_id": "bus1",
      "name": "Bus 1",
      "trips_count": 6
    },
    {
      "route_id": "bus2",
      "name": "Bus 2",
      "trips_count": 5
    },
    {
      "route_id": "bus3",
      "name": "Bus 3",
      "trips_count": 4
    }
  ]
}

Checking Upcoming Buses

Find out when the next buses will arrive at a specific location.

1. Identify your location

   Use the node ID of your current bus stop. You can get available nodes from /api/nodes.

   curl http://localhost:3000/api/nodes
   
2. Query upcoming departures

   Request upcoming buses from your location:

   curl "http://localhost:3000/api/buses/upcoming?from=TILAGOR&limit=5"
   

   The limit parameter controls how many results to return (default: 5, max: 20).

3. Check bus status

   The response shows buses arriving within the next 2 hours:

   {
     "location": {
       "id": "TILAGOR",
       "name": "Tilagor"
     },
     "currentTime": "08:00",
     "count": 3,
     "buses": [
       {
         "route_id": "bus1",
         "route_name": "Bus 1",
         "trip_id": "bus1_0825",
         "departure": "08:25",
         "minutesUntil": 25,
         "destination": "CAMPUS",
         "direction": "to_campus",
         "status": "scheduled"
       },
       {
         "route_id": "bus2",
         "route_name": "Bus 2",
         "trip_id": "bus2_0805",
         "departure": "08:05",
         "minutesUntil": 5,
         "destination": "CAMPUS",
         "direction": "to_campus",
         "status": "soon"
       }
     ]
   }
   

Understanding Bus Status

Each upcoming bus has a status indicator:

Status	Description	Minutes Until
arriving	Bus is arriving now	0
soon	Bus will arrive shortly	1-5 minutes
scheduled	Bus is on schedule	6+ minutes

Use the minutesUntil field to show a countdown timer in your UI, helping students know exactly when to head to the bus stop.

Filtering by Destination

If you only want to see buses going to a specific destination, use the to parameter:

curl "http://localhost:3000/api/buses/upcoming?from=SUBIDBAZAR&to=CAMPUS&limit=3"

This filters out buses that don’t serve your destination or where the destination comes before your current stop.

Trip Directions

Buses operate in two directions:

to_campus

Buses traveling from city locations toward SUST campus. These trips typically run in the morning and early afternoon.

Common stops sequence:

• TILAGOR → SHIBGONJ → NAIORPUL → KUMARPARA → AMBARKHANA → SUBIDBAZAR → CAMPUS

from_campus

Buses returning from campus to city locations. These trips run in the afternoon and evening after classes.

Common stops sequence:

• CAMPUS → SUBIDBAZAR → AMBARKHANA → KUMARPARA → NAIORPUL → SHIBGONJ → TILAGOR

The direction field helps students quickly identify if a bus is heading the right way, especially at major intersections served by multiple routes.

Viewing Full Route Schedule

Get the complete schedule for a specific bus route:

curl http://localhost:3000/api/buses/schedule/bus1

Response Example

{
  "route_id": "bus1",
  "name": "Bus 1",
  "trips": [
    {
      "trip_id": "bus1_0825",
      "direction": "to_campus",
      "departure_time": "08:25",
      "stops": [
        "TILAGOR",
        "SHIBGONJ",
        "NAIORPUL",
        "KUMARPARA",
        "SHAHI_EIDGAH",
        "AMBARKHANA",
        "SUBIDBAZAR",
        "PATHANTULA",
        "MODINA_MARKET",
        "CAMPUS"
      ],
      "stop_count": 10
    },
    {
      "trip_id": "bus1_1310",
      "direction": "from_campus",
      "departure_time": "13:10",
      "stops": [
        "CAMPUS",
        "SUBIDBAZAR",
        "AMBARKHANA",
        "SHAHI_EIDGAH",
        "KUMARPARA",
        "NAIORPUL",
        "SHIBGONJ",
        "TILAGOR"
      ],
      "stop_count": 8
    }
  ]
}

Schedule Format

All schedules use 24-hour time format (HH:MM):

• 08:25 = 8:25 AM
• 13:10 = 1:10 PM
• 17:45 = 5:45 PM

Calculating Arrival Times

The departure_time refers to when the bus leaves its first stop. To estimate arrival at subsequent stops:

// Average 5 minutes per stop
const stopIndex = trip.stops.indexOf('KUMARPARA'); // e.g., index 3
const minutesFromStart = stopIndex * 5; // 15 minutes
const arrivalTime = addMinutes(trip.departure_time, minutesFromStart);
// Result: If bus departs at 08:25, arrives at KUMARPARA around 08:40

This is an estimate. Actual arrival times may vary based on traffic conditions. The system uses 5 minutes as the average time between consecutive stops.

Getting Route Details

For detailed information about a route including all stops and their metadata:

curl http://localhost:3000/api/routes/bus1

Response Example

{
  "route_id": "bus1",
  "name": "Bus 1",
  "total_trips": 6,
  "stops": [
    {
      "id": "TILAGOR",
      "name": "Tilagor",
      "type": "stop"
    },
    {
      "id": "CAMPUS",
      "name": "Campus",
      "type": "destination"
    }
  ],
  "trips": [
    {
      "trip_id": "bus1_0825",
      "direction": "to_campus",
      "departure_time": "08:25",
      "stops": ["TILAGOR", "SHIBGONJ", ...]
    }
  ]
}

Advanced Use Cases

Building a Real-Time Display

Create a live departure board for a bus stop:

// Fetch upcoming buses every 30 seconds
setInterval(async () => {
  const response = await fetch(
    'http://localhost:3000/api/buses/upcoming?from=TILAGOR&limit=5'
  );
  const data = await response.json();
  
  updateDisplay(data.buses);
}, 30000);

Checking If a Bus Has Passed

function hasBusPassed(departure, currentTime) {
  const [depHour, depMin] = departure.split(':').map(Number);
  const [currHour, currMin] = currentTime.split(':').map(Number);
  
  const depMinutes = depHour * 60 + depMin;
  const currMinutes = currHour * 60 + currMin;
  
  // Consider bus "passed" if more than 5 minutes ago
  return (currMinutes - depMinutes) > 5;
}

The upcoming buses endpoint automatically filters out buses that have already departed more than 30 minutes ago, so you don’t need to handle that logic yourself.

Finding Common Routes

Find which routes serve both your origin and destination:

function findCommonRoutes(from, to) {
  const routes = await fetch('http://localhost:3000/api/routes/list');
  const commonRoutes = [];
  
  for (const route of routes) {
    const details = await fetch(`http://localhost:3000/api/routes/${route.route_id}`);
    
    for (const trip of details.trips) {
      const fromIndex = trip.stops.indexOf(from);
      const toIndex = trip.stops.indexOf(to);
      
      if (fromIndex !== -1 && toIndex !== -1 && fromIndex < toIndex) {
        commonRoutes.push(route);
        break;
      }
    }
  }
  
  return commonRoutes;
}

Schedule Data Structure

The schedule system uses a graph-based data model stored in routes.json:

{
  "route_id": "bus1",
  "name": "Bus 1",
  "trips": [
    {
      "trip_id": "bus1_0825",
      "direction": "to_campus",
      "departure_time": "08:25",
      "stops": ["TILAGOR", "SHIBGONJ", "CAMPUS"]
    }
  ]
}

Each trip represents a single bus journey with:

• Unique trip ID (format: {route_id}_{departure_time})
• Direction indicator
• Ordered list of stops
• Departure time from the first stop

Related Endpoints

• Planning Routes - Find the best route using these schedules
• Saving Favorites - Save your regular bus routes
• Authentication - Secure access to schedule data