User API

The User API allows you to manage user profiles, check XP (experience points), and view user statistics.

Endpoints

GET /api/user

Get the current authenticated user's profile information.

Authentication: Required (Session or API Token)

Example Request:

curl https://bubblymaps.org/api/user \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "user": {
    "id": "user123",
    "name": "John Doe",
    "email": "john@example.com",
    "xp": 450,
    "level": 5,
    "isModerator": false,
    "createdAt": "2024-01-10T08:30:00Z",
    "updatedAt": "2024-01-22T15:45:00Z",
    "stats": {
      "waypointsCreated": 12,
      "waypointsEdited": 25,
      "reviewsPosted": 18
    }
  }
}

Error Responses:

401 Unauthorized - User not authenticated
500 Internal Server Error - Failed to fetch user data

GET /api/user/[id]

Get a specific user's public profile information by their user ID.

Authentication: Not required

URL Parameters:

id (string) - User ID

Example Request:

curl https://bubblymaps.org/api/user/user123

Response:

{
  "user": {
    "id": "user123",
    "name": "John Doe",
    "xp": 450,
    "level": 5,
    "createdAt": "2024-01-10T08:30:00Z",
    "stats": {
      "waypointsCreated": 12,
      "waypointsEdited": 25,
      "reviewsPosted": 18
    }
  }
}

Note: Email and other private information are not included in public profile responses.

Error Responses:

404 Not Found - User does not exist
500 Internal Server Error - Failed to fetch user data

PATCH /api/user

Update the current user's profile information.

Authentication: Required (Session)

Request Body:

{
  "name": "Jane Doe",
  "email": "jane@example.com"
}

Optional Fields:

name (string) - User's display name
email (string) - User's email address

Example Request:

curl -X PATCH https://bubblymaps.org/api/user \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_COOKIE" \
  -d '{
    "name": "Jane Doe"
  }'

Response:

{
  "user": {
    "id": "user123",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "xp": 450,
    "level": 5,
    "isModerator": false,
    "createdAt": "2024-01-10T08:30:00Z",
    "updatedAt": "2024-01-23T10:15:00Z",
    "stats": {
      "waypointsCreated": 12,
      "waypointsEdited": 25,
      "reviewsPosted": 18
    }
  }
}

Error Responses:

401 Unauthorized - User not authenticated
400 Bad Request - Invalid data provided
500 Internal Server Error - Failed to update user

GET /api/user/leaderboard

Get the top users by XP on the platform.

Authentication: Not required

Query Parameters:

limit (number, optional) - Number of users to return (default: 10, max: 100)
offset (number, optional) - Pagination offset (default: 0)

Example Request:

curl "https://bubblymaps.org/api/user/leaderboard?limit=5"

Response:

{
  "leaderboard": [
    {
      "id": "user456",
      "name": "Top Contributor",
      "xp": 2450,
      "level": 24,
      "stats": {
        "waypointsCreated": 87,
        "waypointsEdited": 156,
        "reviewsPosted": 203
      }
    },
    {
      "id": "user789",
      "name": "Power User",
      "xp": 1850,
      "level": 18,
      "stats": {
        "waypointsCreated": 45,
        "waypointsEdited": 98,
        "reviewsPosted": 112
      }
    }
  ],
  "total": 567
}

Error Responses:

400 Bad Request - Invalid query parameters
500 Internal Server Error - Failed to fetch leaderboard

Data Model

User Object

Field	Type	Description
`id`	string	Unique user identifier
`name`	string	User's display name
`email`	string	User's email (private, only in own profile)
`xp`	number	Experience points earned
`level`	number	User level calculated from XP
`isModerator`	boolean	Whether user has moderator privileges
`createdAt`	string	Account creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)
`stats`	object	User contribution statistics

User Stats Object

Field	Type	Description
`waypointsCreated`	number	Number of waypoints created
`waypointsEdited`	number	Number of waypoints edited
`reviewsPosted`	number	Number of reviews posted

XP System

Users earn XP (experience points) for contributing to the platform:

Create a waypoint: 50 XP
Edit a waypoint: 10 XP
Post a review: 5 XP
Waypoint gets verified: 25 XP bonus

Level Calculation

User level is calculated based on total XP:

Level 1: 0-99 XP
Level 2: 100-249 XP
Level 3: 250-499 XP
Level 4: 500-999 XP
Level 5+: Every 200 XP = 1 level

XP Requirements

Certain actions require minimum XP:

Create waypoint: 20 XP required
Edit waypoint: 10 XP required
Post review: No XP requirement

Note: API tokens bypass all XP requirements.

Usage Examples

JavaScript/Fetch - Get Current User

async function getCurrentUser() {
  const response = await fetch('https://bubblymaps.org/api/user', {
    credentials: 'include' // Include session cookie
  });
  
  if (!response.ok) {
    throw new Error('Failed to fetch user');
  }
  
  return await response.json();
}

// Usage
getCurrentUser()
  .then(data => console.log('User:', data.user))
  .catch(error => console.error('Error:', error));

JavaScript/Fetch - Update User Profile

async function updateUserProfile(name, email) {
  const response = await fetch('https://bubblymaps.org/api/user', {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
    },
    credentials: 'include',
    body: JSON.stringify({ name, email })
  });
  
  if (!response.ok) {
    throw new Error('Failed to update profile');
  }
  
  return await response.json();
}

// Usage
updateUserProfile('Jane Smith', 'jane.smith@example.com')
  .then(data => console.log('Updated user:', data.user))
  .catch(error => console.error('Error:', error));

Python - Get User Leaderboard

import requests

def get_leaderboard(limit=10):
    url = f"https://bubblymaps.org/api/user/leaderboard?limit={limit}"
    response = requests.get(url)
    
    if response.status_code == 200:
        return response.json()['leaderboard']
    else:
        raise Exception(f"Failed to fetch leaderboard: {response.status_code}")

# Usage
top_users = get_leaderboard(5)
for i, user in enumerate(top_users, 1):
    print(f"{i}. {user['name']} - {user['xp']} XP (Level {user['level']})")

Python - Get Public User Profile

import requests

def get_user_profile(user_id):
    url = f"https://bubblymaps.org/api/user/{user_id}"
    response = requests.get(url)
    
    if response.status_code == 200:
        return response.json()['user']
    else:
        raise Exception(f"Failed to fetch user profile: {response.status_code}")

# Usage
user = get_user_profile('user123')
print(f"Name: {user['name']}")
print(f"Level: {user['level']} (XP: {user['xp']})")
print(f"Waypoints: {user['stats']['waypointsCreated']}")
print(f"Reviews: {user['stats']['reviewsPosted']}")

Use Cases

The User API is useful for:

User Profiles - Display user information and statistics
Leaderboards - Show top contributors
Gamification - Track XP and levels
Authentication - Get current user information
Account Management - Update user profile settings
Community Features - Find and recognize active contributors

User API

On this page