External data sources - Daily GeoGame

Daily GeoGame relies on three primary external data sources for country information, hints, and map visualization.

RestCountries API

Free REST API providing comprehensive data about world countries.

Purpose

Used for:

Country autocomplete: Base country list from countries.json
Detailed country data: Fetched on guess submission
Target country selection: During daily game generation
Geographic info: Coordinates, borders, area, population
Visual elements: Flag SVG URLs

Endpoints used

Get country by alpha code

GET https://restcountries.com/v3.1/alpha/{code}

Example:

curl https://restcountries.com/v3.1/alpha/FR

Response:

[
  {
    "name": {
      "common": "France",
      "official": "French Republic"
    },
    "cca2": "FR",
    "cca3": "FRA",
    "latlng": [46.0, 2.0],
    "borders": ["AND", "BEL", "DEU", "ITA", "LUX", "MCO", "ESP", "CHE"],
    "area": 551695,
    "population": 67391582,
    "flags": {
      "png": "https://flagcdn.com/w320/fr.png",
      "svg": "https://flagcdn.com/fr.svg"
    },
    "region": "Europe",
    "subregion": "Western Europe",
    "languages": {
      "fra": "French"
    },
    "currencies": {
      "EUR": {
        "name": "Euro",
        "symbol": "€"
      }
    }
  }
]

Data transformation

Raw API data is transformed into the Country type:

const countryData: Country = {
  name: details.name.common,
  alpha2Code: details.cca2,
  alpha3Code: details.cca3,
  latlng: details.latlng,
  borders: details.borders,
  area: details.area,
  population: details.population,
  flag: details.flags.svg,
  region: details.region,
  subregion: details.subregion
};

Reference: app/hooks/useDailyGame.ts:155-166

Caching strategy

The /api/country route proxies RestCountries with Next.js caching:

const res = await fetch(`https://restcountries.com/v3.1/alpha/${code}`, {
  cache: 'force-cache' // Cache indefinitely
});

Reference: app/api/country/route.ts:11-13 Why cache?

Country data rarely changes
Reduces external API calls
Faster response times
No rate limiting concerns

Local fallback

A static countries.json file contains basic info for all countries:

[
  {
    "name": "France",
    "alpha2": "FR",
    "alpha3": "FRA",
    "fipsCode": "fr"
  }
]

Reference: app/hooks/useDailyGame.ts:4 This file is used for:

Autocomplete dropdown population
Initial country selection during game generation
Fallback if RestCountries is unavailable

Rate limits

RestCountries is free with no official rate limits, but the app caches responses to be respectful.

Attribution

License: Public domain / CC0 Credit: Listed in README.md

- **Data**: [RestCountries](https://restcountries.com)

Reference: README.md:49

CIA World Factbook

JSON-formatted dataset derived from the CIA World Factbook, providing detailed country information for game hints.

Purpose

Used for generating 6 hint packages:

Climate: Weather patterns and climate zones
Terrain: Geographic landscape descriptions
Resources: Natural resources and agriculture
Trade: Export commodities and industries
Society: Demographics, religions, languages
Symbols: Flag descriptions and national symbols

Data source

Repository: https://github.com/factbook/factbook.json Base URL:

const BASE_URL = "https://raw.githubusercontent.com/factbook/factbook.json/master";

Reference: app/lib/factbook.ts:19

Regional structure

Data is organized into 11 regional folders:

const REGIONS = [
  "africa",
  "antarctica",
  "australia-oceania",
  "central-america-n-caribbean",
  "central-asia",
  "east-n-southeast-asia",
  "europe",
  "middle-east",
  "north-america",
  "south-america",
  "south-asia"
];

Reference: app/lib/factbook.ts:5-17

Fetching data

The fetchFactbookData function iterates through all regions:

export async function fetchFactbookData(fipsCode: string) {
  for (const region of REGIONS) {
    try {
      const url = `${BASE_URL}/${region}/${fipsCode.toLowerCase()}.json`;
      const response = await axios.get(url);
      if (response.status === 200) {
        return response.data;
      }
    } catch (e) {
      // Not found, try next region
    }
  }
  return null;
}

Reference: app/lib/factbook.ts:28-42 Example URL: https://raw.githubusercontent.com/factbook/factbook.json/master/europe/fr.json

Data structure

{
  "Geography": {
    "Climate": {
      "text": "generally cool temperate; more continental climate..."
    },
    "Terrain": {
      "text": "mostly flat plains or gently rolling hills..."
    },
    "Natural resources": {
      "text": "coal, iron ore, bauxite, zinc, uranium, antimony..."
    }
  },
  "Economy": {
    "Exports - commodities": {
      "text": "machinery and transportation equipment, aircraft..."
    },
    "Industries": {
      "text": "machinery, chemicals, automobiles, metallurgy..."
    },
    "Agricultural products": {
      "text": "wheat, cereals, sugar beets, potatoes, wine grapes..."
    }
  },
  "People and Society": {
    "Religions": {
      "text": "Christian (overwhelmingly Roman Catholic) 63-66%..."
    }
  },
  "Government": {
    "Flag description": {
      "text": "three equal vertical bands of blue (hoist side)..."
    },
    "National symbol(s)": {
      "text": "Gallic rooster, fleur-de-lis, Marianne"
    }
  }
}

Hint generation

The generateHintPackages function extracts and formats hint data:

export function generateHintPackages(data: any, basicData?: any): HintPackage[] {
  const hints: HintPackage[] = [];
  
  // Climate hint
  hints.push({
    title: "Climate",
    hints: [{ 
      label: "Weather", 
      value: smartTruncate(data.Geography?.Climate?.text, 130)
    }]
  });
  
  // Terrain hint
  hints.push({
    title: "Terrain",
    hints: [{
      label: "Landscape",
      value: smartTruncate(data.Geography?.Terrain?.text, 130)
    }]
  });
  
  // ... 4 more hints
  
  return hints;
}

Reference: app/lib/factbook.ts:44-118

Text truncation

Long descriptions are truncated to fit the UI:

function smartTruncate(str: string, len = 130) {
  if (!str) return "No data";
  if (str.length <= len) return str;
  const sub = str.substring(0, len);
  return sub.substring(0, sub.lastIndexOf(" ")) + "...";
}

Reference: app/lib/factbook.ts:21-26 This ensures hints:

Don’t overflow UI elements
End at word boundaries
Have consistent ”…” suffix

Fallback data

If Factbook data is missing for specific fields:

let climateVal = "No climate data.";
if (data?.Geography?.Climate?.text) {
  climateVal = smartTruncate(data.Geography.Climate.text);
}

Reference: app/lib/factbook.ts:47-50 If no Factbook data exists for a country, the game generation retries with a different country (up to 5 attempts). Reference: app/api/daily/route.ts:79-94

Update frequency

The Factbook JSON repository is updated periodically by its maintainers. Daily GeoGame fetches data fresh during game generation (not cached).

Attribution

License: Public domain (U.S. government work) Credit: Listed in README.md

- **Data**: [CIA World Factbook](https://github.com/factbook/factbook.json)

Reference: README.md:49

SimpleMaps

Provides the world map SVG file for interactive visualization.

Purpose

Used for:

Map rendering: Base SVG world map
Country highlighting: Show guesses and target
Interactive features: Zoom, pan, country selection

Data type

SVG (Scalable Vector Graphics) file with:

Country polygons as <path> elements
Country codes as id or data-id attributes
Projection: Mercator or similar

Integration

The map is loaded using react-svg and manipulated with D3:

import { ReactSVG } from 'react-svg';
import { geoPath, geoMercator } from 'd3-geo';

<ReactSVG 
  src="/world-map.svg" 
  beforeInjection={(svg) => {
    // Add event listeners, styling
  }}
/>

Reference: package.json:21,14

Country highlighting

CSS classes are applied to SVG paths based on game state:

Guessed countries: Highlighted in color
Neighbor countries: Different shade if adjacent to target
Target country: Revealed when game is over
Hover state: Interactive feedback

Zoom and pan

Interactivity is handled by react-zoom-pan-pinch:

import { TransformWrapper, TransformComponent } from 'react-zoom-pan-pinch';

<TransformWrapper
  initialScale={1}
  minScale={1}
  maxScale={10}
>
  <TransformComponent>
    <ReactSVG src="/world-map.svg" />
  </TransformComponent>
</TransformWrapper>

Reference: package.json:22

Attribution

Source: SimpleMaps Credit: Listed in README.md

- **Map**: [SimpleMaps](https://simplemaps.com)

Reference: README.md:50

Verify SimpleMaps’ license terms if using their map data. Some maps require attribution or have commercial restrictions.

Data flow summary

Daily game generation

User guess

Data reliability

RestCountries

Uptime: ~99% based on community reports
Accuracy: High (regularly maintained)
Breaking changes: Versioned API (using v3.1)

CIA Factbook

Uptime: Depends on GitHub availability (~100%)
Accuracy: High (official U.S. government data)
Freshness: Updated quarterly/annually
Gaps: Some small territories lack complete data

SimpleMaps

Uptime: Served from Next.js public folder (100%)
Accuracy: Professional cartography
Updates: Static file (no runtime dependency)

Offline considerations

The app requires external APIs for full functionality, but has fallbacks:

MongoDB unavailable: Game generation works in-memory
RestCountries down: Uses local countries.json for basic info
Factbook missing: Retries with different countries or shows placeholder hints
SimpleMaps: Bundled with app (always available)

Privacy and data usage

All external APIs are accessed server-side (not from client browsers):

No user data sent to external services
No tracking or analytics from data providers
All API calls are for game content only

Future data improvements

Potential enhancements:

Cache Factbook data: Store in MongoDB to reduce external requests
Backup data source: Mirror RestCountries data locally
Image hints: Add capital city photos or landmarks
Historical data: Track country data changes over time
Custom hints: Add difficulty-based hint selection

Setup

Architecture

API Reference

Contributing

Documentation Index

​RestCountries API

​Purpose

​Endpoints used

​Get country by alpha code

​Data transformation

​Caching strategy

​Local fallback

​Rate limits

​Attribution

​CIA World Factbook

​Purpose

​Data source

​Regional structure

​Fetching data

​Data structure

​Hint generation

​Text truncation

​Fallback data

​Update frequency

​Attribution

​SimpleMaps

​Purpose

​Data type

​Integration

​Country highlighting

​Zoom and pan

​Attribution

​Data flow summary

​Daily game generation

​User guess

​Data reliability

​RestCountries

​CIA Factbook

​SimpleMaps

​Offline considerations

​Privacy and data usage

​Future data improvements

Build docs developers (and LLMs) love

RestCountries API

Purpose

Endpoints used

Get country by alpha code

Data transformation

Caching strategy

Local fallback

Rate limits

Attribution

CIA World Factbook

Purpose

Data source

Regional structure

Fetching data

Data structure

Hint generation

Text truncation

Fallback data

Update frequency

Attribution

SimpleMaps

Purpose

Data type

Integration

Country highlighting

Zoom and pan

Attribution

Data flow summary

Daily game generation

User guess

Data reliability

RestCountries

CIA Factbook

SimpleMaps

Offline considerations

Privacy and data usage

Future data improvements