> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/igorek05m/daily-geogame/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /api/stats

> Retrieve global player statistics for a specific date

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

```http theme={null}
GET /api/stats
```

## Query parameters

<ParamField query="date" type="string" required>
  The game date in YYYY-MM-DD format to retrieve statistics for.
</ParamField>

## Response

<ResponseField name="totalPlayers" type="number" required>
  Total number of players who played the game on this date
</ResponseField>

<ResponseField name="totalWinners" type="number" required>
  Number of players who successfully guessed the country
</ResponseField>

<ResponseField name="winRate" type="number" required>
  Percentage of players who won (0-100), rounded to nearest integer
</ResponseField>

<ResponseField name="guessDistribution" type="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.
</ResponseField>

## Aggregation logic

The guess distribution is calculated using MongoDB aggregation:

```typescript theme={null}
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

```bash theme={null}
curl https://yourdomain.com/api/stats?date=2026-03-02
```

## Example response

```json theme={null}
{
  "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

<Note>
  The `guessDistribution` only includes winners. Players who exhausted all 6 guesses without winning are counted in `totalPlayers` but not in the distribution.
</Note>

## Error responses

**Missing date parameter:**

```json theme={null}
{
  "error": "Date required"
}
```

Status: `400`

**Server error:**

```json theme={null}
{
  "error": "Internal Error"
}
```

Status: `500`

## Code example

```typescript theme={null}
// 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)

<Warning>
  This endpoint requires a database connection and will fail with a 500 error if MongoDB is unavailable.
</Warning>