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

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

<Steps>
  <Step title="Select your origin location">
    Choose from the 19 available nodes in the network. Each node represents a bus stop, intersection, or destination in Sylhet.

    ```bash theme={null}
    # Get list of all available nodes
    curl http://localhost:3000/api/nodes
    ```

    Response includes node details:

    ```json theme={null}
    {
      "count": 19,
      "nodes": [
        {
          "id": "TILAGOR",
          "name": "Tilagor",
          "type": "stop"
        },
        {
          "id": "CAMPUS",
          "name": "Campus",
          "type": "destination"
        }
      ]
    }
    ```
  </Step>

  <Step title="Request route options">
    Call the route planning endpoint with your origin, destination, and desired departure time.

    ```bash theme={null}
    curl "http://localhost:3000/api/routes?from=TILAGOR&to=CAMPUS&time=08:00"
    ```

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

  <Step title="Review route options">
    The API returns multiple route options, each with detailed leg information.

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

## Route Types

The planner considers multiple routing strategies:

### Direct Bus Routes

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

```json theme={null}
{
  "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.

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

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

### Transfer Routes

Switch between two buses at a common stop.

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

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

### Local-Only Fallback

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

```json theme={null}
{
  "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.

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

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

## Using Current Route Context

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

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

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

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

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

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

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

## Related Endpoints

See the related documentation:

* [Viewing Schedules](/guides/viewing-schedules) - Check bus departure times
* [Saving Favorites](/guides/saving-favorites) - Save frequently used routes
* [Authentication](/guides/authentication) - Secure your API requests