> ## 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.
# 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](/guides/authentication) for details on obtaining an auth token.
## Getting Your Favorites
Retrieve all saved favorites for the authenticated user:
```bash theme={null}
curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
http://localhost:3000/api/favorites
```
```json theme={null}
{
"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:
Include your auth token in the Authorization header:
```bash theme={null}
Authorization: Bearer YOUR_AUTH_TOKEN
```
Send a POST request with the route information:
```bash theme={null}
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".
On success, you'll receive the created favorite:
```json theme={null}
{
"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:
```bash theme={null}
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.
```json theme={null}
{
"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:
```bash theme={null}
curl -X DELETE \
-H "Authorization: Bearer YOUR_AUTH_TOKEN" \
http://localhost:3000/api/favorites/550e8400-e29b-41d4-a716-446655440000
```
Successful deletion returns:
```json theme={null}
{
"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:
```javascript theme={null}
const response = await fetch('http://localhost:3000/api/favorites', {
headers: {
'Authorization': 'Bearer YOUR_AUTH_TOKEN'
}
});
const { favorites } = await response.json();
```
```javascript theme={null}
const favorite = favorites[0]; // "Home to Campus"
```
```javascript theme={null}
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"error": "Not found",
"message": "Favorite not found or does not belong to you"
}
```
**HTTP Status:** 404 Not Found
## Best Practices
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"
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.
* 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:
```json theme={null}
{
"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](/guides/authentication) - Required for saving favorites
* [Planning Routes](/guides/planning-routes) - Use saved favorites to quickly plan routes
* [Viewing Schedules](/guides/viewing-schedules) - Check bus times for your favorite routes