Skip to main content
Returns aggregated statistics showing how all players performed on a specific daily game, including total players, winners, win rate, and the distribution of guesses needed to win.

​
Endpoint

GET /api/stats

​
Query parameters

​
date
string
required
The game date in YYYY-MM-DD format to retrieve statistics for.

​
Response

​
totalPlayers
number
required
Total number of players who played the game on this date
​
totalWinners
number
required
Number of players who successfully guessed the country
​
winRate
number
required
Percentage of players who won (0-100), rounded to nearest integer
​
guessDistribution
Record<string, number>
required
Object mapping the number of guesses to the count of winners who won with that many guesses.Keys are strings representing guess counts (“1”, “2”, “3”, etc.) Values are the number of players who won with that many guesses.

​
Aggregation logic

The guess distribution is calculated using MongoDB aggregation: 
const distribution = await collection.aggregate([
    { $match: { date: date, won: true } },
    { $project: { numberOfGuesses: { $size: "$guesses" } } },
    { $group: { _id: "$numberOfGuesses", count: { $sum: 1 } } },
    { $sort: { _id: 1 } }
]).toArray();
From app/api/stats/route.ts:18-23 This pipeline:
  1. Filters to only games on the specified date that were won
  2. Calculates the number of guesses for each game
  3. Groups by guess count and counts occurrences
  4. Sorts by guess count ascending

​
Example request

curl https://yourdomain.com/api/stats?date=2026-03-02

​
Example response

{
  "totalPlayers": 150,
  "totalWinners": 98,
  "winRate": 65,
  "guessDistribution": {
    "1": 5,
    "2": 18,
    "3": 32,
    "4": 25,
    "5": 12,
    "6": 6
  }
}
In this example:
  • 150 players attempted the game
  • 98 players won (65% win rate)
  • 5 players guessed correctly on their first try
  • 32 players needed 3 guesses to win
  • 52 players (150 - 98) did not win
The guessDistribution only includes winners. Players who exhausted all 6 guesses without winning are counted in totalPlayers but not in the distribution.

​
Error responses

Missing date parameter: 
{
  "error": "Date required"
}
Status: 400 Server error: 
{
  "error": "Internal Error"
}
Status: 500

​
Code example

// Fetch global stats for today's game
const fetchStats = async (date: string) => {
  const response = await fetch(`/api/stats?date=${date}`);
  const stats = await response.json();
  
  console.log(`${stats.totalPlayers} players, ${stats.winRate}% win rate`);
  
  // Display guess distribution
  Object.entries(stats.guessDistribution).forEach(([guesses, count]) => {
    console.log(`${count} players won in ${guesses} guesses`);
  });
  
  return stats;
};

​
Use cases

This endpoint is used to:
  • Display global leaderboard statistics
  • Show how the user’s performance compares to others
  • Generate histogram visualizations of guess distributions
  • Calculate difficulty metrics for daily games
  • Show engagement metrics (total player count)
This endpoint requires a database connection and will fail with a 500 error if MongoDB is unavailable.