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

GET /api/daily

Query parameters

date · 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

date · string · required

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

hintPackages · HintPackage[] · required

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

Show HintPackage properties

title · string · required

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

hints · Hint[] · required

Array of individual hints within this package

Show Hint properties

label · string · required

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

value · string · required

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

targetCountry · 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)

name · string

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

alpha2Code · string

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

alpha3Code · string

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

latlng · number[]

Coordinates as [latitude, longitude]

borders · string[]

Array of alpha-3 codes for bordering countries

area · number

Country area in square kilometers

population · number

Country population

flag · string

SVG flag URL

region · string

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

subregion · 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:

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

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