Viewing Schedules

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.

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

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).

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

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

Get Started

Core Concepts

User Guides

Viewing Schedules

Available Bus Routes

Get All Routes

Checking Upcoming Buses

Understanding Bus Status

Filtering by Destination

Trip Directions

Viewing Full Route Schedule

Schedule Format

Calculating Arrival Times

Getting Route Details

Advanced Use Cases

Building a Real-Time Display

Checking If a Bus Has Passed

Finding Common Routes

Schedule Data Structure

Build docs developers (and LLMs) love

Get Started

Core Concepts

User Guides

Documentation Index

​Available Bus Routes

​Get All Routes

​Checking Upcoming Buses

​Understanding Bus Status

​Filtering by Destination

​Trip Directions

​Viewing Full Route Schedule

​Schedule Format

​Calculating Arrival Times

​Getting Route Details

​Advanced Use Cases

​Building a Real-Time Display

​Checking If a Bus Has Passed

​Finding Common Routes

​Schedule Data Structure

​Related Endpoints

Build docs developers (and LLMs) love

Available Bus Routes

Get All Routes

Checking Upcoming Buses

Understanding Bus Status

Filtering by Destination

Trip Directions

Viewing Full Route Schedule

Schedule Format

Calculating Arrival Times

Getting Route Details

Advanced Use Cases

Building a Real-Time Display

Checking If a Bus Has Passed

Finding Common Routes

Schedule Data Structure

Related Endpoints