> ## 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.

# Statistics

> Track your progress and compare yourself with players worldwide using Daily GeoGame's comprehensive statistics system

## Overview

Daily GeoGame tracks both personal and global statistics, giving you insight into your performance and how you compare with the worldwide player community. Stats are calculated per daily challenge and persist across sessions.

### What's tracked

<CardGroup cols={2}>
  <Card title="Personal stats" icon="user">
    * Games played
    * Total wins
    * Win rate percentage
    * Current date progress
  </Card>

  <Card title="Global stats" icon="globe">
    * Total players for the day
    * Total winners for the day
    * Global win rate
    * Guess distribution chart
  </Card>
</CardGroup>

<Info>
  Statistics are calculated in real-time as players complete challenges. Your personal stats update immediately after each game, while global stats refresh when you open the statistics modal.
</Info>

## Session tracking

Daily GeoGame uses browser cookies to maintain your session and track progress across page reloads:

### How sessions work

<Steps>
  <Step title="First visit">
    When you first play Daily GeoGame, the system generates a unique session ID and stores it in a browser cookie named `geo_session`.
  </Step>

  <Step title="Progress saved">
    Each guess you make is saved to the MongoDB database, linked to your session ID and the current date.
  </Step>

  <Step title="Persistent state">
    If you close your browser and return later, your session cookie allows the game to restore your exact progress for each date.
  </Step>

  <Step title="Multi-device">
    Sessions are device-specific. Playing on your phone creates a different session than your laptop, so progress doesn't sync across devices.
  </Step>
</Steps>

### Session data structure

Your session progress is stored in the `user_progress` MongoDB collection with these fields:

* `sessionId`: Your unique identifier (from cookie)
* `date`: The challenge date (YYYY-MM-DD format)
* `guesses`: Array of country objects you've guessed
* `won`: Boolean indicating if you correctly identified the target
* `createdAt`: Timestamp of when you started this challenge
* `updatedAt`: Timestamp of your last guess

<Note>
  Sessions are anonymous—the system doesn't collect personal information. Your session ID is a random string with no connection to your identity.
</Note>

## Win rate calculation

Win rates are calculated as percentages, showing the proportion of games won versus games played.

### Personal win rate

Your personal win rate is calculated by the `/api/progress` endpoint:

```
Win Rate = (Total Wins / Games Played) × 100
```

For example:

* Played 20 games
* Won 15 games
* Win rate: (15 / 20) × 100 = 75%

### Global win rate

The global win rate shows how difficult each daily challenge is:

```
Global Win Rate = (Total Winners / Total Players) × 100
```

This is calculated per date by the `/api/stats/route.ts:30-33` endpoint:

* Counts total players who attempted the challenge
* Counts total players who successfully won
* Divides and rounds to nearest whole percentage

<Accordion title="Why do win rates vary by date?">
  Some countries are harder to identify than others. Small island nations or countries with less distinctive features tend to have lower global win rates, while larger or more well-known countries have higher win rates. Tracking win rates per date helps you understand which challenges were especially difficult.
</Accordion>

## Guess distribution

The guess distribution chart shows how many guesses it took winners to identify the target country. This is displayed as a horizontal bar chart with values 1-6.

### How it's calculated

The `/api/stats/route.ts:18-23` endpoint uses MongoDB aggregation:

1. Filters to only winning players (`won: true`) for the specific date
2. Counts the length of each winner's `guesses` array
3. Groups by number of guesses (1, 2, 3, 4, 5, or 6)
4. Returns the count for each group

For example, on a given day:

* 5 players won on guess 1
* 12 players won on guess 2
* 23 players won on guess 3
* 18 players won on guess 4
* 9 players won on guess 5
* 3 players won on guess 6

### Interpreting the distribution

The distribution reveals challenge difficulty and player strategy:

<AccordionGroup>
  <Accordion title="High guess 1-2 counts">
    Indicates an easier challenge or that many players recognized the country quickly from the first hints.
  </Accordion>

  <Accordion title="Peak at guess 3-4">
    Suggests a moderate difficulty where most players needed several hints to narrow down the answer.
  </Accordion>

  <Accordion title="High guess 5-6 counts">
    Reveals a difficult challenge where players needed nearly all hints to identify the target.
  </Accordion>

  <Accordion title="Skewed distributions">
    Unusual patterns (like most wins at guess 6) indicate particularly obscure countries that stumped even successful players.
  </Accordion>
</AccordionGroup>

### Visual representation

The chart (`/app/components/StatsModal.tsx:86-111`) displays as horizontal bars:

* Each row represents one guess number (1-6)
* Bar width is proportional to the count relative to the maximum value
* Your winning guess is highlighted in green (if you won)
* Other bars appear in gray
* The count appears inside each bar (if space allows)

<Note>
  Bars are scaled relative to the maximum count, not to 100%. This ensures the chart always fills the available space and differences are visible even with small counts.
</Note>

## Statistics modal

Access your detailed statistics by clicking the stats button in the game header. The modal displays comprehensive information organized into three sections:

### Game result section

**Shown**: Only after game completion (win or loss)

* Victory or defeat banner with color-coded header
* Target country name in large, bold text
* Country flag image
* "Learn more" link to Wikipedia article about the country

This section provides closure and educational opportunity—you can explore more about the country you just discovered.

### Global metrics section

**Shown**: Always

Two stat cards display side-by-side:

<CardGroup cols={2}>
  <Card title="Total Players" icon="users" color="#3B82F6">
    Number of unique sessions that attempted today's challenge
  </Card>

  <Card title="Win Rate" icon="percent" color="#EAB308">
    Percentage of players who successfully identified the target country
  </Card>
</CardGroup>

### Guess distribution section

**Shown**: Always

A detailed bar chart showing the distribution of guesses among winning players, as described above. Your winning guess (if applicable) is highlighted to show where you fall in the distribution.

<Info>
  The statistics modal updates in real-time. If you win a challenge and immediately open the stats modal, you'll see your result included in the global counts.
</Info>

## API endpoints

Statistics are powered by two backend routes:

### GET /api/progress

Retrieves your personal progress for a specific date:

**Query parameters**: `date` (YYYY-MM-DD format)\
**Returns**:

```json theme={null}
{
  "guesses": [...],
  "won": true,
  "stats": {
    "gamesPlayed": 15,
    "wins": 12,
    "winRate": 80
  }
}
```

### GET /api/stats

Retrieves global statistics for a specific date:

**Query parameters**: `date` (YYYY-MM-DD format)\
**Returns**:

```json theme={null}
{
  "totalPlayers": 1247,
  "totalWinners": 891,
  "winRate": 71,
  "guessDistribution": {
    "1": 45,
    "2": 178,
    "3": 312,
    "4": 234,
    "5": 98,
    "6": 24
  }
}
```

<Warning>
  Both endpoints require a valid date parameter in YYYY-MM-DD format. Invalid or missing dates return a 400 error.
</Warning>

## Using statistics strategically

Leverage stats to improve your gameplay:

### Identify your patterns

* **High guess counts**: Review challenges where you needed 5-6 guesses and study what made them difficult
* **Low guess counts**: Identify country types you recognize quickly to understand your geographic strengths
* **Win rate trends**: Track how your win rate changes over time as you learn more geography

### Learn from the community

* **Compare distributions**: If most players needed 5-6 guesses but you won in 2, you likely have strong knowledge of that region
* **Identify hard challenges**: Low global win rates indicate universally difficult countries—study these for future reference
* **Benchmark yourself**: Is your win rate higher or lower than the global average? Use this to set improvement goals

### Track progress over time

While Daily GeoGame doesn't currently show historical trends, you can manually track:

* Daily win/loss records
* Average number of guesses when you win
* Regions you struggle with most
* Personal best streaks

<Card title="Pro tip" icon="lightbulb">
  Keep a spreadsheet or journal of each day's challenge. Note the target country, your guess count, and what hints helped you most. Over time, you'll identify patterns in your geographic knowledge and areas for improvement.
</Card>

## Privacy and data retention

Daily GeoGame respects your privacy with minimal data collection:

* **No accounts required**: You play anonymously with a session cookie
* **No personal data**: The system doesn't collect names, emails, or identifying information
* **Session-based**: Data is tied to random session IDs, not individuals
* **Local storage**: Your browser stores the session cookie; the server only stores gameplay data
* **No tracking**: No third-party analytics or advertising trackers are used

Your statistics exist to enhance your gameplay experience, not to profile or monetize your activity.