> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ihfaz297/MND/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
curl http://localhost:3000/api/routes/list
```

<Accordion title="Response Example">
  ```json theme={null}
  {
    "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
      }
    ]
  }
  ```
</Accordion>

## Checking Upcoming Buses

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

<Steps>
  <Step title="Identify your location">
    Use the node ID of your current bus stop. You can get available nodes from `/api/nodes`.

    ```bash theme={null}
    curl http://localhost:3000/api/nodes
    ```
  </Step>

  <Step title="Query upcoming departures">
    Request upcoming buses from your location:

    ```bash theme={null}
    curl "http://localhost:3000/api/buses/upcoming?from=TILAGOR&limit=5"
    ```

    <Note>
      The `limit` parameter controls how many results to return (default: 5, max: 20).
    </Note>
  </Step>

  <Step title="Check bus status">
    The response shows buses arriving within the next 2 hours:

    ```json theme={null}
    {
      "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"
        }
      ]
    }
    ```
  </Step>
</Steps>

## 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    |

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

## Filtering by Destination

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

```bash theme={null}
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:

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

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

## Viewing Full Route Schedule

Get the complete schedule for a specific bus route:

```bash theme={null}
curl http://localhost:3000/api/buses/schedule/bus1
```

<Accordion title="Response Example">
  ```json theme={null}
  {
    "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
      }
    ]
  }
  ```
</Accordion>

## 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:

```javascript theme={null}
// 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
```

<Note>
  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.
</Note>

## Getting Route Details

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

```bash theme={null}
curl http://localhost:3000/api/routes/bus1
```

<Accordion title="Response Example">
  ```json theme={null}
  {
    "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", ...]
      }
    ]
  }
  ```
</Accordion>

## Advanced Use Cases

### Building a Real-Time Display

Create a live departure board for a bus stop:

```javascript theme={null}
// 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

```javascript theme={null}
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;
}
```

<Tip>
  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.
</Tip>

### Finding Common Routes

Find which routes serve both your origin and destination:

```javascript theme={null}
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`:

```json theme={null}
{
  "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](/guides/planning-routes) - Find the best route using these schedules
* [Saving Favorites](/guides/saving-favorites) - Save your regular bus routes
* [Authentication](/guides/authentication) - Secure access to schedule data