Bus Information

Overview

The bus information endpoints provide real-time access to bus schedules, upcoming departures, and detailed route information for all 7 university bus routes.

Get Upcoming Buses

Find the next buses departing from a specific location.

GET /api/buses/upcoming?from=TILAGOR&limit=5

Query Parameters

from

string

required

Origin node ID. The location where you’re waiting for a bus.Example: TILAGOR, CAMPUS, SUBIDBAZAR

string

Optional destination node ID. Filters results to only show buses that go to this destination.Example: CAMPUS, MEDICAL

limit

number

default:"5"

Maximum number of results to return. Clamped between 1 and 20.Example: 10

time

string

Current time in HH:MM format. Defaults to current system time.Example: 08:30

Response Fields

location

object

The location information

Show properties

string

Node ID

name

string

Human-readable location name

currentTime

string

Current or requested time in HH:MM format

count

number

Number of upcoming buses found

buses

object[]

Array of upcoming bus departures, sorted by departure time

Show Bus Properties

route_id

string

Bus route identifier (e.g., “bus1”, “bus2”)

route_name

string

Human-readable route name (e.g., “Bus 1”)

trip_id

string

Unique trip identifier

departure

string

Departure time from this stop (HH:MM)

minutesUntil

number

Minutes until departure (0 if arriving now)

destination

string

Final destination node ID

direction

string

Trip direction: to_campus or from_campus

status

string

Bus status:

arriving: Departing now (0 minutes)
soon: Departing within 5 minutes
scheduled: Departing later

Error Responses

Missing Origin (400)

{
  "error": "Missing origin",
  "message": "Please provide \"from\" parameter"
}

Invalid Location (404)

{
  "error": "Invalid location",
  "message": "Location \"INVALID\" not found"
}

Get Route Schedule

Get the complete schedule for a specific bus route.

GET /api/buses/schedule/bus1

Path Parameters

routeId

string

required

Bus route identifier. Valid values: bus1 through bus7

Response Fields

route_id

string

Route identifier

name

string

Human-readable route name

trips

object[]

Array of scheduled trips for this route. See BusSchedule model.

Get Route Details

Get detailed information about a bus route, including all served stops.

GET /api/routes/bus3

Path Parameters

routeId

string

required

Bus route identifier. Valid values: bus1 through bus7

Response Fields

route_id

string

Route identifier

name

string

Human-readable route name

total_trips

number

Total number of scheduled trips per day

stops

object[]

Array of all unique stops served by this route (across all trips)

trips

object[]

Complete trip information with stop sequences

List All Routes

Get a summary of all available bus routes.

GET /api/routes/list

Bus Route Coverage

Morning Routes (to Campus)

Most buses run morning routes between 7:30 AM and 9:35 AM:

Bus 1: Tilagor → Campus (via Shahi Eidgah)
Bus 2: Tilagor → Campus (via Shahi Eidgah)
Bus 3: Naiorpul → Campus (via Jail Rd, Chowhatta)
Bus 4: Naiorpul → Campus (via Jail Rd, Chowhatta)
Bus 5: Lakkatura → Campus (via Ambarkhana)
Bus 6: Naiorpul/Shahi Eidgah → Campus
Bus 7: Sheikhghat/Shahi Eidgah → Campus

Afternoon/Evening Routes (from Campus)

Return routes typically run at:

13:10 (1:10 PM)
16:10 (4:10 PM)
17:10 (5:10 PM)
18:30 (6:30 PM)

Trip Directions

to_campus

Buses heading towards the university campus (morning commute).

{
  "direction": "to_campus",
  "departure_time": "08:30",
  "stops": ["TILAGOR", "SHIBGONJ", ..., "CAMPUS"]
}

from_campus

Buses departing from campus (afternoon/evening).

{
  "direction": "from_campus",
  "departure_time": "17:10",
  "stops": ["CAMPUS", "SUBIDBAZAR", ..., "TILAGOR"]
}

Usage Examples

Find Next Bus to Campus

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

Check If Bus Serves Your Route

# Get Bus 1 schedule
curl "http://localhost:3000/api/buses/schedule/bus1"

# Check if KUMARPARA and CAMPUS are both in stops array

Plan Around Bus Schedule

# 1. Check upcoming buses
curl "http://localhost:3000/api/buses/upcoming?from=TILAGOR&time=08:00"

# 2. If no buses soon, plan alternative route
curl "http://localhost:3000/api/routes?from=TILAGOR&to=CAMPUS&time=08:00"

Route Planning

Find complete routes with bus + local transport

Nodes

See all available stops

Bus Schedule Model

Trip data structure

Health Check

Get total route count

Overview

Endpoints

Data Models

Bus Information

Overview

Get Upcoming Buses

Query Parameters

Response Fields

Error Responses

Get Route Schedule

Path Parameters

Response Fields

Get Route Details

Path Parameters

Response Fields

List All Routes

Bus Route Coverage

Morning Routes (to Campus)

Afternoon/Evening Routes (from Campus)

Trip Directions

to_campus

from_campus

Usage Examples

Find Next Bus to Campus

Check If Bus Serves Your Route

Plan Around Bus Schedule

Route Planning

Nodes

Bus Schedule Model

Health Check

Build docs developers (and LLMs) love

Overview

Endpoints

Data Models

Documentation Index

​Overview

​Get Upcoming Buses

​Query Parameters

​Response Fields

​Error Responses

​Get Route Schedule

​Path Parameters

​Response Fields

​Get Route Details

​Path Parameters

​Response Fields

​List All Routes

​Bus Route Coverage

​Morning Routes (to Campus)

​Afternoon/Evening Routes (from Campus)

​Trip Directions

​to_campus

​from_campus

​Usage Examples

​Find Next Bus to Campus

​Check If Bus Serves Your Route

​Plan Around Bus Schedule

​Related Endpoints

Route Planning

Nodes

Bus Schedule Model

Health Check

Build docs developers (and LLMs) love

Overview

Get Upcoming Buses

Query Parameters

Response Fields

Error Responses

Get Route Schedule

Path Parameters

Response Fields

Get Route Details

Path Parameters

Response Fields

List All Routes

Bus Route Coverage

Morning Routes (to Campus)

Afternoon/Evening Routes (from Campus)

Trip Directions

to_campus

from_campus

Usage Examples

Find Next Bus to Campus

Check If Bus Serves Your Route

Plan Around Bus Schedule

Related Endpoints