Saving Favorites

Save and manage your frequently used routes for quick access

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:

1. Authenticate your request

   Include your auth token in the Authorization header:

   Authorization: Bearer YOUR_AUTH_TOKEN
   
2. 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”.

3. 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:

1. Fetch your favorites

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

   const favorite = favorites[0]; // "Home to Campus"
   
3. 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)

Related Documentation

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