API Overview

Complete reference for the MND University Bus Routing API

Introduction

The MND API provides intelligent route planning for the university bus system, connecting 19 locations across Sylhet, Bangladesh with 7 bus routes. The API combines real-time bus schedules with local transport options to find the fastest and most economical routes.

Base URL

http://localhost:3000/api

For network access (same WiFi):

http://[YOUR_NETWORK_IP]:3000/api

Available Endpoints

Core Endpoints

• GET /health - System health and statistics
• GET /nodes - List all 19 available locations
• GET /routes/list - List all 7 bus routes
• GET /routes - Plan a route between two locations

Authentication Endpoints

• POST /auth/send-link - Send magic login link
• GET /auth/verify - Verify magic link and create session
• POST /auth/logout - Logout and invalidate token
• GET /profile - Get authenticated user profile

Favorites Endpoints (Requires Authentication)

• GET /favorites - Get user’s saved routes
• POST /favorites - Save a new favorite route
• PUT /favorites/:id - Update a favorite route
• DELETE /favorites/:id - Delete a favorite route

Bus Information Endpoints

• GET /buses/upcoming - Get upcoming buses from a location
• GET /buses/schedule/:routeId - Get full schedule for a route
• GET /routes/:routeId - Get detailed route information

Response Format

All API responses use JSON format:

Success Response

{
  "status": "success",
  "data": { ... }
}

Error Response

{
  "error": "Error type",
  "message": "Human-readable error message",
  "details": { ... }
}

Error Handling

The API uses standard HTTP status codes:

Status Code	Description
200	Success
201	Created (for POST requests)
400	Bad Request - Invalid parameters
401	Unauthorized - Authentication required
404	Not Found - Resource doesn’t exist
409	Conflict - Duplicate resource
500	Internal Server Error

Common Error Scenarios

Invalid Node ID

{
  "error": "Invalid origin node",
  "message": "Node 'INVALID' not found",
  "hint": "Use GET /api/nodes to see available nodes"
}

Invalid Time Format

{
  "error": "Invalid time format",
  "message": "Time '25:00' is not in HH:MM format",
  "example": "08:30"
}

Authentication Required

{
  "error": "Unauthorized",
  "message": "Authentication required"
}

CORS Configuration

The API is configured with permissive CORS settings for development:

app.use(cors());

This allows requests from any origin. In production, configure specific allowed origins:

app.use(cors({
  origin: ['https://yourdomain.com'],
  credentials: true
}));

Rate Limiting

The API uses Google Distance Matrix API for local transport calculations with the following limits:

• Monthly Limit: 700 requests
• Daily Limit: 25 requests
• Cache: Results are cached to minimize API usage

Network Information

The API provides network statistics in the health endpoint:

{
  "status": "healthy",
  "graph": {
    "nodes": 19,
    "routes": 7
  },
  "distanceMatrix": {
    "available": true,
    "usage": {
      "monthly": "45/700",
      "daily": "12/25"
    },
    "cache": {
      "hits": 234,
      "misses": 45,
      "hitRate": "84%"
    }
  }
}

Data Freshness

The API loads graph data (nodes, edges, routes) on startup from JSON files:

src/data/
  ├── nodes.json    # 19 locations
  ├── edges.json    # Connections between locations
  └── routes.json   # 7 bus routes with schedules

Restart the server to reload updated data.

Next Steps

Authentication

Learn how to implement magic link authentication

Route Planning

Plan routes between locations

Nodes

Browse all 19 available locations

Buses

Get real-time bus information