> ## 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/daily

> Retrieve the daily geography challenge with progressive hints

Returns the daily geography game including hint packages that unlock progressively based on the user's guess count. Hints are partially revealed until the game is complete.

## Endpoint

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

## Query parameters

<ParamField query="date" type="string" optional>
  Target date in YYYY-MM-DD format. Defaults to today's date if not provided.

  **Validation**: Must match the pattern `^\d{4}-\d{2}-\d{2}$`
</ParamField>

## Response

<ResponseField name="date" type="string" required>
  The date of this daily game in YYYY-MM-DD format
</ResponseField>

<ResponseField name="hintPackages" type="HintPackage[]" required>
  Array of hint packages. Each package unlocks after a guess is made.

  <Expandable title="HintPackage properties">
    <ResponseField name="title" type="string" required>
      The category title (e.g., "Geography", "Population", "Economy")
    </ResponseField>

    <ResponseField name="hints" type="Hint[]" required>
      Array of individual hints within this package

      <Expandable title="Hint properties">
        <ResponseField name="label" type="string" required>
          The hint label (e.g., "Capital", "Population")
        </ResponseField>

        <ResponseField name="value" type="string" required>
          The hint value. Shows `"???"` if the hint is locked, otherwise shows the actual value
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="targetCountry" type="Country | null" required>
  The target country details. Only revealed when the game is over (6 guesses made or game won). Returns `null` during active gameplay.

  <Expandable title="Country properties (when revealed)">
    <ResponseField name="name" type="string">
      Country name (e.g., "Poland")
    </ResponseField>

    <ResponseField name="alpha2Code" type="string">
      ISO 3166-1 alpha-2 country code (e.g., "PL")
    </ResponseField>

    <ResponseField name="alpha3Code" type="string">
      ISO 3166-1 alpha-3 country code (e.g., "POL")
    </ResponseField>

    <ResponseField name="latlng" type="number[]">
      Coordinates as `[latitude, longitude]`
    </ResponseField>

    <ResponseField name="borders" type="string[]">
      Array of alpha-3 codes for bordering countries
    </ResponseField>

    <ResponseField name="area" type="number">
      Country area in square kilometers
    </ResponseField>

    <ResponseField name="population" type="number">
      Country population
    </ResponseField>

    <ResponseField name="flag" type="string">
      SVG flag URL
    </ResponseField>

    <ResponseField name="region" type="string">
      Geographic region (e.g., "Europe")
    </ResponseField>

    <ResponseField name="subregion" type="string">
      Geographic subregion (e.g., "Central Europe")
    </ResponseField>
  </Expandable>
</ResponseField>

## Hint unlock logic

Hints are progressively revealed based on gameplay:

* **Initial state**: First hint package is unlocked (1 package visible)
* **After each guess**: One additional hint package unlocks
* **Maximum guesses**: 6 attempts
* **Game over**: All hints become visible when the game ends

```typescript theme={null}
const allowedHintsCount = guessesCount + 1;
```

From `app/api/daily/route.ts:140`

## Example request

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

## Example response

**During gameplay (game not finished):**

```json theme={null}
{
  "date": "2026-03-02",
  "hintPackages": [
    {
      "title": "Geography",
      "hints": [
        { "label": "Continent", "value": "Europe" },
        { "label": "Capital", "value": "Warsaw" }
      ]
    },
    {
      "title": "Demographics",
      "hints": [
        { "label": "Population", "value": "???" },
        { "label": "Area", "value": "???" }
      ]
    }
  ],
  "targetCountry": null
}
```

**After game completion:**

```json theme={null}
{
  "date": "2026-03-02",
  "hintPackages": [
    {
      "title": "Geography",
      "hints": [
        { "label": "Continent", "value": "Europe" },
        { "label": "Capital", "value": "Warsaw" }
      ]
    },
    {
      "title": "Demographics",
      "hints": [
        { "label": "Population", "value": "38,000,000" },
        { "label": "Area", "value": "312,696 km²" }
      ]
    }
  ],
  "targetCountry": {
    "name": "Poland",
    "alpha2Code": "PL",
    "alpha3Code": "POL",
    "latlng": [52, 20],
    "borders": ["DEU", "CZE", "SVK", "UKR", "BLR", "LTU", "RUS"],
    "area": 312696,
    "population": 38000000,
    "flag": "https://flagcdn.com/pl.svg",
    "region": "Europe",
    "subregion": "Central Europe"
  }
}
```

## Error responses

**Invalid date format:**

```json theme={null}
{
  "error": "Invalid date format. Expected YYYY-MM-DD"
}
```

Status: `400`

**Server error:**

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

Status: `500`

## Game generation

If no game exists for the requested date, the API automatically generates one:

1. Selects a random country from the countries database
2. Fetches details from RestCountries API
3. Retrieves CIA World Factbook data
4. Generates hint packages from factbook data
5. Stores the game in MongoDB (if available)
6. Falls back to Poland if no valid country is found after 5 attempts

<Note>
  The daily game is consistent for all users on a given date. Once generated, it's cached in the database.
</Note>

<Warning>
  If the database connection fails, the game is generated in-memory and will not persist across requests. This may result in different games for the same date.
</Warning>

## Code example

```typescript theme={null}
// Fetch today's daily game
const response = await fetch('/api/daily');
const game = await response.json();

// Fetch a specific date
const response = await fetch('/api/daily?date=2026-03-01');
const pastGame = await response.json();

// Check if game is over
if (game.targetCountry) {
  console.log('Game over! Answer:', game.targetCountry.name);
}
```