Saving Favorites

The favorites system allows authenticated users to save their commonly traveled routes for quick access, eliminating the need to repeatedly enter origin and destination details.

Overview

Favorites are saved routes with:

Custom labels (e.g., “Home to Campus”, “Morning Commute”)
Origin and destination nodes
Optional default departure time
Per-user storage with a limit of 10 favorites

Authentication is required to use the favorites feature. See the Authentication guide for details on obtaining an auth token.

Getting Your Favorites

Retrieve all saved favorites for the authenticated user:

curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  http://localhost:3000/api/favorites

Response Example

{
  "count": 3,
  "favorites": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "label": "Home to Campus",
      "from": "TILAGOR",
      "to": "CAMPUS",
      "defaultTime": "08:00",
      "createdAt": "2026-03-01T08:30:00.000Z"
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "label": "Return Home",
      "from": "CAMPUS",
      "to": "TILAGOR",
      "defaultTime": "17:00",
      "createdAt": "2026-03-01T08:35:00.000Z"
    },
    {
      "id": "c5aa5c2d-5d73-4c85-a6f0-7a8f0c9c2d1e",
      "label": "Library from Home",
      "from": "KUMARPARA",
      "to": "SUBIDBAZAR",
      "defaultTime": "14:00",
      "createdAt": "2026-03-02T10:15:00.000Z"
    }
  ]
}

Creating a Favorite

Save a new favorite route:

Authenticate your request

Include your auth token in the Authorization header:

Authorization: Bearer YOUR_AUTH_TOKEN

Provide route details

Send a POST request with the route information:

curl -X POST \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Morning Class",
    "from": "NAIORPUL",
    "to": "CAMPUS",
    "defaultTime": "08:30"
  }' \
  http://localhost:3000/api/favorites

The defaultTime field is optional. If omitted, it defaults to “08:00”.

Handle the response

On success, you’ll receive the created favorite:

{
  "success": true,
  "message": "Favorite saved",
  "favorite": {
    "id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
    "label": "Morning Class",
    "from": "NAIORPUL",
    "to": "CAMPUS",
    "defaultTime": "08:30",
    "createdAt": "2026-03-05T06:00:00.000Z"
  }
}

Required Fields

Field	Type	Description
`label`	string	Display name for the favorite (e.g., “Home to Campus”)
`from`	string	Origin node ID (must be a valid node in the network)
`to`	string	Destination node ID (must be a valid node)
`defaultTime`	string	Optional default departure time in HH:MM format

Updating a Favorite

Modify the label or default time of an existing favorite:

curl -X PUT \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Updated Label",
    "defaultTime": "09:00"
  }' \
  http://localhost:3000/api/favorites/550e8400-e29b-41d4-a716-446655440000

You can update either the label, defaultTime, or both. The from and to fields cannot be changed - create a new favorite instead.

Response Example

{
  "success": true,
  "message": "Favorite updated",
  "favorite": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "label": "Updated Label",
    "from": "TILAGOR",
    "to": "CAMPUS",
    "defaultTime": "09:00",
    "createdAt": "2026-03-01T08:30:00.000Z"
  }
}

Deleting a Favorite

Remove a favorite route:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  http://localhost:3000/api/favorites/550e8400-e29b-41d4-a716-446655440000

Successful deletion returns:

{
  "success": true,
  "message": "Favorite deleted",
  "deleted": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "label": "Home to Campus"
  }
}

Using Favorites for Quick Route Planning

Once you have favorites saved, you can use them to quickly plan routes:

Fetch your favorites

const response = await fetch('http://localhost:3000/api/favorites', {
  headers: {
    'Authorization': 'Bearer YOUR_AUTH_TOKEN'
  }
});
const { favorites } = await response.json();

Select a favorite

const favorite = favorites[0]; // "Home to Campus"

Plan the route

const routeResponse = await fetch(
  `http://localhost:3000/api/routes?from=${favorite.from}&to=${favorite.to}&time=${favorite.defaultTime}`
);
const route = await routeResponse.json();

Error Handling

Duplicate Favorites

If you try to save a route that’s already in your favorites:

{
  "error": "Duplicate favorite",
  "message": "This route is already saved",
  "existing": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "label": "Home to Campus"
  }
}

HTTP Status: 409 Conflict

Limit Reached

Each user can save a maximum of 10 favorites:

{
  "error": "Limit reached",
  "message": "Maximum 10 favorites allowed. Please delete some to add more."
}

HTTP Status: 400 Bad Request

Before creating a new favorite, check if you’re at the limit and prompt the user to delete old favorites if needed.

Invalid Node IDs

If the from or to node doesn’t exist:

{
  "error": "Invalid node",
  "message": "Node 'INVALID_NODE' not found in the network"
}

HTTP Status: 400 Bad Request

Unauthorized Access

Attempting to access favorites without authentication:

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

HTTP Status: 401 Unauthorized

Favorite Not Found

Trying to update or delete a favorite that doesn’t exist or doesn’t belong to you:

{
  "error": "Not found",
  "message": "Favorite not found or does not belong to you"
}

HTTP Status: 404 Not Found

Best Practices

Naming Conventions

Use descriptive labels that make sense at a glance:Good labels:

“Home to Campus (Morning)”
“Campus to Library”
“Weekend Market Trip”

Poor labels:

“Route 1”
“TILAGOR to CAMPUS”
“A”

Setting Default Times

Choose default times based on your regular schedule:

Morning commute: Set to your typical departure time (e.g., “08:00”)
Return trips: Use your usual class end time (e.g., “17:00”)
Flexible routes: Use “08:00” as a neutral default

Users can always override the default time when planning a route.

Managing the 10-favorite limit

Delete seasonal favorites (e.g., routes used only during exam week)
Combine similar routes with generic labels
Keep only your most frequent trips
Regularly review and remove unused favorites

Favorites Data Storage

Favorites are stored in the favorites.json file on the server:

{
  "favorites": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user-123",
      "label": "Home to Campus",
      "from": "TILAGOR",
      "to": "CAMPUS",
      "defaultTime": "08:00",
      "createdAt": "2026-03-01T08:30:00.000Z"
    }
  ]
}

Each favorite is linked to a userId ensuring users can only see and modify their own favorites.

Implementation Reference

The favorites feature is implemented in src/api/favoritesController.ts:

GET /api/favorites - Returns all favorites for the authenticated user (line 58)
POST /api/favorites - Creates a new favorite with validation and deduplication (line 97)
PUT /api/favorites/:id - Updates label or defaultTime for a favorite (line 250)
DELETE /api/favorites/:id - Removes a favorite from the user’s list (line 189)

Authentication - Required for saving favorites
Planning Routes - Use saved favorites to quickly plan routes
Viewing Schedules - Check bus times for your favorite routes

Get Started

Core Concepts

User Guides

Saving Favorites

Overview

Getting Your Favorites

Creating a Favorite

Required Fields

Updating a Favorite

Deleting a Favorite

Using Favorites for Quick Route Planning

Error Handling

Duplicate Favorites

Limit Reached

Invalid Node IDs

Unauthorized Access

Favorite Not Found

Best Practices

Favorites Data Storage

Implementation Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

User Guides

Documentation Index

​Overview

​Getting Your Favorites

​Creating a Favorite

​Required Fields

​Updating a Favorite

​Deleting a Favorite

​Using Favorites for Quick Route Planning

​Error Handling

​Duplicate Favorites

​Limit Reached

​Invalid Node IDs

​Unauthorized Access

​Favorite Not Found

​Best Practices

​Favorites Data Storage

​Implementation Reference

​Related Documentation

Build docs developers (and LLMs) love

Overview

Getting Your Favorites

Creating a Favorite

Required Fields

Updating a Favorite

Deleting a Favorite

Using Favorites for Quick Route Planning

Error Handling

Duplicate Favorites

Limit Reached

Invalid Node IDs

Unauthorized Access

Favorite Not Found

Best Practices

Favorites Data Storage

Implementation Reference

Related Documentation