Planning Routes

Learn how to plan optimal routes from any location to campus using the MND route planning API

The MND route planner finds the best way to get from any location in Sylhet to campus by combining university bus routes with local transport options.

Overview

The route planner analyzes multiple transport combinations and returns up to 3 optimal routes categorized as:

• Fastest Route: Minimizes total travel time including wait time
• Least Local Transport: Minimizes use of CNG/rickshaw to reduce costs

Planning a Route

Use the /api/routes endpoint to plan a route between any two locations.

1. Select your origin location

   Choose from the 19 available nodes in the network. Each node represents a bus stop, intersection, or destination in Sylhet.

   # Get list of all available nodes
   curl http://localhost:3000/api/nodes
   

   Response includes node details:

   {
     "count": 19,
     "nodes": [
       {
         "id": "TILAGOR",
         "name": "Tilagor",
         "type": "stop"
       },
       {
         "id": "CAMPUS",
         "name": "Campus",
         "type": "destination"
       }
     ]
   }
   
2. Request route options

   Call the route planning endpoint with your origin, destination, and desired departure time.

   curl "http://localhost:3000/api/routes?from=TILAGOR&to=CAMPUS&time=08:00"
   

   The time parameter should be in 24-hour format (HH:MM). If omitted, it defaults to the current time.

3. Review route options

   The API returns multiple route options, each with detailed leg information.

   {
     "from": "TILAGOR",
     "to": "CAMPUS",
     "requestTime": "08:00",
     "options": [
       {
         "label": "Fastest Route",
         "category": "fastest",
         "type": "direct",
         "transfers": 0,
         "totalTimeMin": 70,
         "totalCost": 0,
         "localTimeMin": 0,
         "localDistanceMeters": 0,
         "usesDistanceMatrix": false,
         "legs": []
       }
     ]
   }
   

Route Types

The planner considers multiple routing strategies:

Direct Bus Routes

A single bus takes you from origin to destination without transfers.

{
  "label": "Bus 1 Direct",
  "type": "direct",
  "transfers": 0,
  "legs": [
    {
      "mode": "bus",
      "route_id": "bus1",
      "trip_id": "bus1_0825",
      "from": "TILAGOR",
      "to": "CAMPUS",
      "departure": "08:25",
      "arrival": "09:10",
      "durationMin": 45,
      "cost": 0,
      "source": "graph"
    }
  ]
}

Bus + Local Hybrid

Take the bus as far as possible, then use local transport (CNG/rickshaw) for the remaining distance.

{
  "label": "Bus 2 + Local",
  "type": "direct",
  "transfers": 0,
  "legs": [
    {
      "mode": "bus",
      "route_id": "bus2",
      "from": "KUMARPARA",
      "to": "AMBARKHANA",
      "departure": "08:15",
      "arrival": "08:35",
      "durationMin": 20,
      "cost": 0
    },
    {
      "mode": "local",
      "submode": "driving",
      "from": "AMBARKHANA",
      "to": "CAMPUS",
      "durationMin": 15,
      "distanceMeters": 4200,
      "cost": 84,
      "source": "distance_matrix"
    }
  ]
}

Local transport costs are estimated at 2 BDT per 100 meters based on typical CNG fares in Sylhet.

Transfer Routes

Switch between two buses at a common stop.

{
  "label": "Transfer at Subidbazar",
  "type": "transfer",
  "transfers": 1,
  "legs": [
    {
      "mode": "bus",
      "route_id": "bus1",
      "from": "TILAGOR",
      "to": "SUBIDBAZAR",
      "departure": "08:25",
      "arrival": "08:55"
    },
    {
      "mode": "bus",
      "route_id": "bus3",
      "from": "SUBIDBAZAR",
      "to": "CAMPUS",
      "departure": "09:05",
      "arrival": "09:20"
    }
  ]
}

Transfer routes are only suggested if the wait time at the transfer point is 15 minutes or less.

Local-Only Fallback

When no bus routes are available or you’ve missed the bus, the planner provides a local-only option.

{
  "label": "Local Transport Only",
  "category": "least_local",
  "type": "local_only",
  "transfers": 0,
  "totalTimeMin": 25,
  "totalCost": 120,
  "localTimeMin": 25,
  "legs": [
    {
      "mode": "local",
      "submode": "driving",
      "from": "TILAGOR",
      "to": "CAMPUS",
      "durationMin": 25,
      "distanceMeters": 6000,
      "cost": 120,
      "source": "distance_matrix"
    }
  ]
}

Understanding Route Legs

Each route consists of one or more legs representing a segment of the journey.

Bus Leg Fields

Field	Type	Description
mode	string	Always “bus” for bus legs
route_id	string	Bus route identifier (e.g., “bus1”)
trip_id	string	Specific trip identifier with departure time
from	string	Origin node ID
to	string	Destination node ID
departure	string	Departure time in HH:MM format
arrival	string	Arrival time in HH:MM format
durationMin	number	Travel time in minutes
cost	number	Cost in BDT (always 0 for buses)
source	string	”graph” indicates schedule-based timing

Local Transport Leg Fields

Field	Type	Description
mode	string	”local” for CNG/rickshaw/car
submode	string	”driving” or “walking”
from	string	Origin node ID
to	string	Destination node ID
durationMin	number	Estimated travel time
distanceMeters	number	Distance in meters
cost	number	Estimated cost in BDT
source	string	”distance_matrix” or “graph”

Using Current Route Context

When planning a route while already on a bus, provide the currentRoute parameter to get updated options.

curl "http://localhost:3000/api/routes?from=AMBARKHANA&to=CAMPUS&time=08:30&currentRoute=bus1"

This helps the planner understand your current position and provide relevant transfer options.

Map Visualization

The route response includes node IDs that correspond to physical locations with latitude/longitude coordinates. Use these to render the route on a map using Google Maps Directions API or similar services.

Rendering Route Legs

For each leg in the route:

1. Bus legs: Draw a polyline connecting the stops along the route
2. Local legs: Use Google Maps Directions API to get turn-by-turn directions and polylines
3. Walking legs: Show straight-line or walking path between points

Example: Flutter Map Integration

// Extract node coordinates from the route
for (var leg in route.legs) {
  final fromNode = nodes.firstWhere((n) => n.id == leg.from);
  final toNode = nodes.firstWhere((n) => n.id == leg.to);
  
  if (leg.mode == 'bus') {
    // Draw bus route polyline
    drawBusRoute(fromNode, toNode, leg.routeId);
  } else if (leg.mode == 'local') {
    // Fetch directions from Google Maps
    final directions = await getDirections(fromNode, toNode);
    drawPolyline(directions.polyline);
  }
}

Best Practices

Optimizing for different scenarios

• Morning commute: Request routes 30 minutes before you need to arrive to account for wait times
• Returning from campus: Use “from_campus” direction buses which have different schedules
• Late arrivals: If you miss the bus, the local-only fallback ensures you can still get to campus
• Cost-conscious: Look for the “Least Local Transport” option to minimize expenses

Handling API responses

• Always check if options array is empty - this means no routes are available
• Sort options by totalTimeMin or totalCost based on user preference
• Show category badges (“Fastest”, “Least Local”) in the UI
• Display transfers count prominently - students often prefer direct routes

Related Endpoints

See the related documentation:

• Viewing Schedules - Check bus departure times
• Saving Favorites - Save frequently used routes
• Authentication - Secure your API requests