GET /api/daily

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

GET /api/daily

Query parameters

string

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}$

Response

string

required

The date of this daily game in YYYY-MM-DD format

HintPackage[]

required

Array of hint packages. Each package unlocks after a guess is made.

Show HintPackage properties

string

required

The category title (e.g., “Geography”, “Population”, “Economy”)

Hint[]

required

Array of individual hints within this package

Show Hint properties

string

required

The hint label (e.g., “Capital”, “Population”)

string

required

The hint value. Shows "???" if the hint is locked, otherwise shows the actual value

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.

Show Country properties (when revealed)

string

Country name (e.g., “Poland”)

string

ISO 3166-1 alpha-2 country code (e.g., “PL”)

string

ISO 3166-1 alpha-3 country code (e.g., “POL”)

number[]

Coordinates as [latitude, longitude]

string[]

Array of alpha-3 codes for bordering countries

number

Country area in square kilometers

number

Country population

string

SVG flag URL

string

Geographic region (e.g., “Europe”)

string

Geographic subregion (e.g., “Central Europe”)

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

const allowedHintsCount = guessesCount + 1;

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

Example request

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

Example response

During gameplay (game not finished):

{
  "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:

{
  "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:

{
  "error": "Invalid date format. Expected YYYY-MM-DD"
}

Status: 400 Server error:

{
  "error": "Internal Server Error"
}

Status: 500

Game generation

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

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

The daily game is consistent for all users on a given date. Once generated, it’s cached in the database.

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.

Code example

// 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);
}

Setup

Architecture

API Reference

Contributing

Endpoint

Query parameters

Response

Hint unlock logic

Example request

Example response

Error responses

Game generation

Code example

​Endpoint

​Query parameters

​Response

​Hint unlock logic

​Example request

​Example response

​Error responses

​Game generation

​Code example

Endpoint

Query parameters

Response

Hint unlock logic

Example request

Example response

Error responses

Game generation

Code example