Skip to main content

​
Overview

The Saved Locations API allows authenticated users to manage their favorite locations with full Create, Read, Update, and Delete (CRUD) functionality. All operations are user-scoped and require authentication.

​
Get All Saved Locations

curl https://autonomous.stu.nighthawkcodingsociety.com/api/saved_locations \
  -H "Content-Type: application/json" \
  -H "X-Origin: client" \
  --include-credentials
Retrieves all saved locations. Results are automatically filtered to show only locations belonging to the authenticated user.

​
Response

Returns an array of saved location objects.
​
[].id
number
Unique location identifier
​
[].user_name
string
Display name for the location (e.g., “Home”, “Office”, “Gym”)
​
[].user_address
string
Full street address of the location
​
[].username
string
Username of the location owner (matches authenticated user)
​
[].created_at
string
ISO 8601 timestamp when the location was saved

​
Success Response

[
  {
    "id": 1,
    "user_name": "Home",
    "user_address": "123 Poway Rd, Poway, CA 92064",
    "username": "johndoe",
    "created_at": "2026-03-01T10:30:00Z"
  },
  {
    "id": 2,
    "user_name": "Poway High School",
    "user_address": "15500 Espola Rd, Poway, CA 92064",
    "username": "johndoe",
    "created_at": "2026-03-02T14:15:00Z"
  }
]

​
Create Saved Location

curl -X POST https://autonomous.stu.nighthawkcodingsociety.com/api/saved_locations \
  -H "Content-Type: application/json" \
  -H "X-Origin: client" \
  --include-credentials \
  -d '{
    "name": "Favorite Coffee Shop",
    "address": "789 Main St, Poway, CA 92064"
  }'
Creates a new saved location for the authenticated user.

​
Request Body

​
name
string
required
Display name for the location (e.g., “Home”, “Work”, “Gym”)
​
address
string
required
Complete street address

​
Response

​
id
number
Unique identifier for the newly created location
​
message
string
Success confirmation message

​
Success Response

{
  "id": 3,
  "message": "Location saved successfully"
}

​
Real Implementation

From navigation/favoriteLocations/favoriteLocations.js:157-183: 
async function createScores(inputName, inputAddress) {
  const locationData = {
    address: inputAddress,
    name: inputName
  };

  try {
    const response = await fetch(`${pythonURI}/api/saved_locations`, {
      ...fetchOptions,
      method: 'POST',
      body: JSON.stringify(locationData),
    });

    if (!response.ok) {
      throw new Error(`Failed to submit location: ${response.statusText}`);
    }

    const result = await response.json();
    return (result);
  } catch (error) {
    console.error('Error submitting location:', error);
    alert('Error submitting location: ' + error.message);
    return null;
  }
}

​
Update Saved Location

curl -X PUT https://autonomous.stu.nighthawkcodingsociety.com/api/saved_locations \
  -H "Content-Type: application/json" \
  -H "X-Origin: client" \
  --include-credentials \
  -d '{
    "id": 3,
    "name": "Updated Location Name",
    "address": "789 Main St, Poway, CA 92064"
  }'
Updates an existing saved location. Only the location owner can perform updates.

​
Request Body

​
id
number
required
Unique identifier of the location to update
​
name
string
required
Updated display name for the location
​
address
string
required
Updated street address

​
Response

​
message
string
Success confirmation message
​
id
number
ID of the updated location

​
Success Response

{
  "message": "Location updated successfully",
  "id": 3
}

​
Real Implementation

From navigation/favoriteLocations/favoriteLocations.js:214-239: 
async function updateScores(inputId, inputAddress, inputName) {
  const scoreData = {
    id: inputId,
    address: inputAddress,
    name: inputName
  }

  try {
    const response = await fetch(`${pythonURI}/api/saved_locations`, {
      ...fetchOptions,
      method: 'PUT',
      body: JSON.stringify(scoreData),
    });

    if (!response.ok) {
      throw new Error(`Failed to update location: ${response.statusText}`);
    }

    const result = await response.json();
    return (result);
  } catch (error) {
    console.error('Error updating location:', error);
    alert('Error updating location: ' + error.message);
  }
}

​
Delete Saved Location

curl -X DELETE https://autonomous.stu.nighthawkcodingsociety.com/api/saved_locations \
  -H "Content-Type: application/json" \
  -H "X-Origin: client" \
  --include-credentials \
  -d '{
    "id": 3
  }'
Deletes a saved location. Only the location owner can perform deletions.

​
Request Body

​
id
number
required
Unique identifier of the location to delete

​
Response

​
message
string
Success confirmation message

​
Success Response

{
  "message": "Location deleted successfully"
}

​
Real Implementation

From navigation/favoriteLocations/favoriteLocations.js:186-212: 
async function deleteScores(inputId) {
  const scoreData = {
    id: inputId
  }

  try {
    const response = await fetch(`${pythonURI}/api/saved_locations`, {
      ...fetchOptions,
      method: 'DELETE',
      body: JSON.stringify(scoreData),
    });

    if (!response.ok) {
      throw new Error(`Failed to delete location: ${response.statusText}`);
    }

    const result = await response.json();
    return (result);
  } catch (error) {
    console.error('Error deleting location:', error);
    alert('Error deleting location: ' + error.message);
    return null;
  }
}

​
User Filtering

The API automatically filters locations by the authenticated user. The frontend performs additional client-side filtering: 
async function filterForUsername(scores) {
  const currentUserResponse = await fetch(`${pythonURI}/api/user`, fetchOptions);
  if (!currentUserResponse.ok) throw new Error('Failed to fetch current user');
  const currentUser = await currentUserResponse.json();
  let userName = currentUser.name;

  return (scores.filter((entry) => String(entry.username) === String(userName)));
}
All operations require valid user authentication via cookies (credentials: 'include'). Unauthenticated requests will be rejected.

​
Error Responses

​
Authentication Error

{
  "error": "Authentication required"
}

​
Not Found Error

{
  "error": "Location not found"
}

​
Validation Error

{
  "error": "Name and address are required"
}

​
Permission Error

{
  "error": "You do not have permission to modify this location"
}

​
Use Cases

Quick Route Planning

Instantly access frequently visited locations for rapid route calculations

Personalized Navigation

Build a custom library of important places tailored to your daily routine

Time Savings

Avoid repeatedly entering the same addresses for common destinations

Location Organization

Categorize and manage locations with custom names and descriptions

​
Integration with Features

The Saved Locations API powers the Favorite Locations feature, providing:
  • Grid-based UI for browsing saved locations
  • Modal popups for adding and editing locations
  • Inline editing capabilities
  • One-click deletion with confirmation
  • Automatic synchronization with the backend

Build docs developers (and LLMs) love

Get started for freeTalk to us