GET /api/leaderboard

Get leaderboard rankings with privacy filtering

Back to API Docs

Access dynamic leaderboard rankings with privacy filtering and multiple time periods.

Privacy Note: Only users who have enabled public leaderboard visibility appear in results.

Endpoint URL

GET https://game.regardingwork.com/api/leaderboard

Authentication

JWT Bearer token required

📤 Request

Headers

Authorization: Bearer <your_jwt_token>

Query Parameters

period - Time period: "daily", "weekly", "monthly", "all_time" (default: daily)
limit - Maximum number of results (default: 50, max: 100)
metric - Ranking metric: "points", "sessions", "minutes" (default: points)
include_rank - Include current user's rank (true/false, default: true)

✅ Response (200 OK)

{
  "leaderboard": [
    {
      "rank": 1,
      "username": "productivity_ninja",
      "points": 87.5,
      "sessions": 25,
      "minutes": 1125,
      "streak": 8,
      "badge": "power_user",
      "is_current_user": false
    },
    {
      "rank": 2,
      "username": "focus_master",
      "points": 76.2,
      "sessions": 22,
      "minutes": 990,
      "streak": 12,
      "badge": "consistent_week",
      "is_current_user": false
    },
    {
      "rank": 3,
      "username": "janechen",
      "points": 67.3,
      "sessions": 18,
      "minutes": 810,
      "streak": 12,
      "badge": "marathon_session",
      "is_current_user": true
    }
  ],
  "user_rank": {
    "current_rank": 3,
    "total_participants": 47,
    "percentile": 93.6,
    "rank_change": "+2",
    "points_behind_leader": 20.2
  },
  "period_info": {
    "period": "daily",
    "start_date": "2025-08-24",
    "end_date": "2025-08-24",
    "total_users": 47,
    "public_users": 31
  }
}

🏆 Leaderboard Features

Ranking Options

Daily: Today's productivity
Weekly: This week's progress
Monthly: This month's achievements
All Time: Overall productivity ranking

Display Data

User rank and percentile
Rank change indicators (+/-)
Points behind leader
Badges and streaks

💻 Code Examples

JavaScript (Fetch) - Get Weekly Leaderboard

const token = localStorage.getItem('jwt_token');

const response = await fetch('https://game.regardingwork.com/api/leaderboard?period=weekly&limit=10', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const data = await response.json();

// Display current user rank
console.log(`Your rank: #${data.user_rank.current_rank} of ${data.user_rank.total_participants}`);
console.log(`Percentile: ${data.user_rank.percentile}%`);

// Display top performers
data.leaderboard.forEach((user, index) => {
  const crown = index < 3 ? ['🥇', '🥈', '🥉'][index] : '';
  console.log(`${crown} ${user.rank}. ${user.username} - ${user.points} points`);
});

JavaScript - Motivational Messages

// Generate motivational messages based on rank
function getMotivationalMessage(userRank) {
  const { current_rank, percentile, rank_change } = userRank;
  
  if (current_rank === 1) {
    return "🏆 You're #1! Keep up the amazing work!";
  } else if (current_rank <= 3) {
    return `🥉 Top 3! You're in the ${percentile}th percentile!`;
  } else if (rank_change.startsWith('+')) {
    return `📈 Rising ${rank_change} positions! You're climbing!`;
  } else if (percentile > 75) {
    return `⭐ Top ${Math.round(100-percentile)}%! You're doing great!`;
  } else {
    return "💪 Keep pushing! Every session counts!";
  }
}