diff --git a/client/tools/api-docs/bonus.html b/client/tools/api-docs/bonus.html index 77a948bdd..a9d2b8c59 100644 --- a/client/tools/api-docs/bonus.html +++ b/client/tools/api-docs/bonus.html @@ -33,6 +33,8 @@
bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/check-answer.html b/client/tools/api-docs/check-answer.html
index 1c30755e6..19ed8ca66 100644
--- a/client/tools/api-docs/check-answer.html
+++ b/client/tools/api-docs/check-answer.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/frequency-list.html b/client/tools/api-docs/frequency-list.html
index 56f4c9252..96d965fb0 100644
--- a/client/tools/api-docs/frequency-list.html
+++ b/client/tools/api-docs/frequency-list.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/index.html b/client/tools/api-docs/index.html
index 65fb66ee6..9f348ec17 100644
--- a/client/tools/api-docs/index.html
+++ b/client/tools/api-docs/index.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
@@ -152,6 +154,16 @@ GET /leaderboardGET qbreader.org/api/leaderboard+ Rank every user by the number of questions they have heard. + Results are recomputed at most once every five minutes. +
+ +401.
+ key: string
+ Required
+ 401.
+ limit: number
+ Optional
+ 50, and is clamped to the range 1–500.
+ minQuestions: number
+ Optional
+ 0. Applied before limit.
+ object with the following properties:
+ leaderboard: Object[]
+
+ An array of objects, sorted from most to least questions heard.
+ Users who have been deleted are omitted.
+
{
+ _id: string // the user's id
+ username: string
+ tossupCount: number // tossups heard
+ bonusCount: number // bonuses heard
+ total: number // tossupCount + bonusCount
+ numCorrect: number // tossups answered correctly
+ powers: number // tossups buzzed for 15 or more
+ tens: number // tossups buzzed for exactly 10
+ negs: number // tossups buzzed for a negative value
+ tossupPoints: number
+ bonusPoints: number
+ points: number // tossupPoints + bonusPoints
+ pptu: number // points per tossup heard
+ ppb: number // points per bonus heard
+ accuracy: number // numCorrect / tossupCount, from 0 to 1
+ averageCorrectCelerity: number // from 0 to 1; higher means an earlier buzz
+}
+ count: number
+ leaderboard.
+ generatedAt: string
+ 401
+ key parameter is missing or incorrect.503
+ object containing an error string.
+ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/num-packets.html b/client/tools/api-docs/num-packets.html
index 3f36c7424..7b3895f83 100644
--- a/client/tools/api-docs/num-packets.html
+++ b/client/tools/api-docs/num-packets.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/packet.html b/client/tools/api-docs/packet.html
index 3b2b7219f..a74a448aa 100644
--- a/client/tools/api-docs/packet.html
+++ b/client/tools/api-docs/packet.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/query.html b/client/tools/api-docs/query.html
index 629223701..ca75a4905 100644
--- a/client/tools/api-docs/query.html
+++ b/client/tools/api-docs/query.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/question-stats/bonus.html b/client/tools/api-docs/question-stats/bonus.html
index 311de0eb5..12b0aa5f7 100644
--- a/client/tools/api-docs/question-stats/bonus.html
+++ b/client/tools/api-docs/question-stats/bonus.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/question-stats/tossup.html b/client/tools/api-docs/question-stats/tossup.html
index e38641664..b5d145a33 100644
--- a/client/tools/api-docs/question-stats/tossup.html
+++ b/client/tools/api-docs/question-stats/tossup.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/random-bonus.html b/client/tools/api-docs/random-bonus.html
index 1f16b5c8f..25990946e 100644
--- a/client/tools/api-docs/random-bonus.html
+++ b/client/tools/api-docs/random-bonus.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/random-name.html b/client/tools/api-docs/random-name.html
index 371209a7a..c9a3e441e 100644
--- a/client/tools/api-docs/random-name.html
+++ b/client/tools/api-docs/random-name.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/random-tossup.html b/client/tools/api-docs/random-tossup.html
index 6ee5844f6..9ec7ad960 100644
--- a/client/tools/api-docs/random-tossup.html
+++ b/client/tools/api-docs/random-tossup.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/report-question.html b/client/tools/api-docs/report-question.html
index 9a41a4489..037904037 100644
--- a/client/tools/api-docs/report-question.html
+++ b/client/tools/api-docs/report-question.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/schemas/index.html b/client/tools/api-docs/schemas/index.html
index ee06cf52d..d078030cd 100644
--- a/client/tools/api-docs/schemas/index.html
+++ b/client/tools/api-docs/schemas/index.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/set-list.html b/client/tools/api-docs/set-list.html
index f185d160b..16912e79b 100644
--- a/client/tools/api-docs/set-list.html
+++ b/client/tools/api-docs/set-list.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/client/tools/api-docs/tossup.html b/client/tools/api-docs/tossup.html
index 3553525c4..8cd240bdb 100644
--- a/client/tools/api-docs/tossup.html
+++ b/client/tools/api-docs/tossup.html
@@ -33,6 +33,8 @@ bonus
tossup
+ leaderboard
check-answer
random-name
diff --git a/database/account-info/leaderboard.js b/database/account-info/leaderboard.js
index acf8fea7b..3cd8b2464 100644
--- a/database/account-info/leaderboard.js
+++ b/database/account-info/leaderboard.js
@@ -5,41 +5,84 @@ const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
let cachedOverall = null;
let cachedAt = 0;
+/**
+ * @typedef {Object} LeaderboardRow
+ * @property {ObjectId} _id - the user's _id
+ * @property {String} username
+ * @property {Number} tossupCount - tossups heard
+ * @property {Number} bonusCount - bonuses heard
+ * @property {Number} total - tossupCount + bonusCount
+ * @property {Number} numCorrect - tossups answered correctly
+ * @property {Number} powers - tossups buzzed for 15 or more
+ * @property {Number} tens - tossups buzzed for exactly 10
+ * @property {Number} negs - tossups buzzed for a negative value
+ * @property {Number} tossupPoints
+ * @property {Number} bonusPoints
+ * @property {Number} points - tossupPoints + bonusPoints
+ * @property {Number} pptu - points per tossup heard
+ * @property {Number} ppb - points per bonus heard
+ * @property {Number} accuracy - numCorrect / tossupCount, in [0, 1]
+ * @property {Number} averageCorrectCelerity - in [0, 1]; higher means an earlier buzz
+ */
+
+/**
+ * Rank every user by the number of questions they have heard.
+ * Results are cached for five minutes, since the underlying aggregations
+ * unwind the entirety of per-tossup-data and per-bonus-data.
+ * @param {Number} [limit] - the maximum number of rows to return; all rows if falsy.
+ * @returns {Promise