A production-ready FastAPI application for real-time scraping and tracking of Hell Divers 2 game data.

High Command API provides comprehensive access to Hell Divers 2 game statistics, war status, planet information, campaigns, and faction data through a modern RESTful API with automatic background data collection and interactive documentation.

• ✅ Real-time Data Collection: Automatic background scraping every 5 minutes
• ✅ Comprehensive Endpoints: 30+ endpoints for accessing game data
• ✅ Historical Tracking: SQLite database with optimized queries
• ✅ Cache Fallback: Graceful degradation when upstream API is unavailable
• ✅ Interactive Documentation: Auto-generated Swagger UI and ReDoc
• ✅ Production Ready: Docker support, error handling, type hints
• ✅ Developer Friendly: Clean code, extensive documentation

high-command-api/
├── src/                    # Core application code
│   ├── __init__.py
│   ├── app.py             # FastAPI application
│   ├── scraper.py         # Hell Divers 2 API scraper
│   ├── database.py        # SQLite database layer
│   ├── collector.py       # Background task scheduler
│   └── config.py          # Configuration management
├── tests/                  # Test suite
│   ├── __init__.py
│   └── demo.py            # Comprehensive tests
├── docs/                   # Documentation
│   ├── API.md             # API reference
│   ├── ARCHITECTURE.md    # Architecture & design
│   ├── QUICKREF.md        # Quick reference
│   └── DEPLOYMENT.md      # Deployment guide
├── Makefile               # Project automation
├── Dockerfile             # Container image
├── docker-compose.yml     # Multi-container setup
├── requirements.txt       # Python dependencies
├── .env.example          # Environment template
└── pyproject.toml        # Project metadata

Note: Files like *_SUMMARY.md, COMPLETE_GUIDE.md, etc. are development artifacts and can be safely ignored.

• README.md - This file; project overview and quick start
• docs/API.md - Complete API endpoint reference with examples
• docs/ARCHITECTURE.md - System architecture and database schema
• docs/DEVELOPMENT.md - Development guide and patterns
• docs/DEPLOYMENT.md - Production deployment instructions
• .github/copilot-instructions.md - AI coding agent instructions

• Python 3.8+
• pip or pipenv

1. Clone the repository:

cd /home/lee/git/high-command/high-command-api

2. Create a virtual environment:

python3 -m venv venv
source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure environment:

cp .env.example .env

5. Run the application:

python app.py

The API will be available at http://localhost:5000

6. (Optional) Run the demo script to test all endpoints:

python demo.py

After installation, the API is immediately ready to use:

# Start the API
python app.py

# In another terminal, test it
curl http://localhost:5000/api/health

# Run the demo test suite
python demo.py

All endpoints are automatically documented and can be explored interactively:

• Swagger UI: http://localhost:5000/docs
• ReDoc: http://localhost:5000/redoc

• GET /api/war/status - Get current war status
• POST /api/war/status/refresh - Manually refresh war status

• GET /api/campaigns - Get all campaigns
• GET /api/campaigns/active - Get active campaigns

• GET /api/planets - Get all planets
• GET /api/planets/<planet_index> - Get specific planet status
• GET /api/planets/<planet_index>/history?limit=10 - Get planet status history

• GET /api/statistics - Get latest statistics
• GET /api/statistics/history?limit=100 - Get statistics history
• POST /api/statistics/refresh - Manually refresh statistics

• GET /api/factions - Get all factions

• GET /api/biomes - Get all biomes

• GET /api/health - Health check endpoint
• GET / - Root endpoint with API information

Edit .env file to configure:

FLASK_ENV=development          # Environment (development, production, testing)
FLASK_DEBUG=True               # Debug mode
API_PORT=5000                  # API port
DATABASE_URL=sqlite:///helldivers2.db  # Database location
LOG_LEVEL=INFO                 # Logging level
SCRAPE_INTERVAL=300            # Data collection interval in seconds

The API uses SQLite to store:

• war_status: Current and historical war statuses
• statistics: Game-wide statistics with timestamps
• planet_status: Individual planet status snapshots
• campaigns: Active and completed campaigns
• assignments: Major orders and assignments
• dispatches: News and announcements
• planet_events: Special events on planets
• system_status: Internal metadata (e.g., upstream API availability)

All data includes timestamps for historical tracking and analysis.

When the upstream Hell Divers 2 API is unavailable, the following endpoints automatically fall back to cached data:

• /api/campaigns - Returns most recent campaign snapshot
• /api/planets - Returns most recent planets snapshot
• /api/planets/{planet_index} - Returns most recent planet status
• /api/factions - Returns factions from latest war status
• /api/biomes - Returns biomes from latest planet data

These endpoints return 503 Service Unavailable only when both the live API fails AND no cached data is available. This ensures maximum uptime and data availability.

The application automatically collects data on a configurable interval (default 5 minutes):

• War status
• Global statistics
• Planet statuses
• Campaign information

Access the health endpoint to verify the collector is running:

curl http://localhost:5000/api/health

Output:

{
  "status": "healthy",
  "collector_running": true
}

• Framework: FastAPI - Modern, fast Python web framework
• Server: Uvicorn - Lightning-fast ASGI server
• Scheduling: APScheduler - Flexible background task scheduler
• HTTP Client: Requests - Simple and elegant HTTP library
• Database: SQLite - Lightweight, file-based database
• Documentation: Automatic OpenAPI (Swagger) & ReDoc integration

curl http://localhost:5000/api/war/status

curl "http://localhost:5000/api/planets/1/history?limit=20"

curl "http://localhost:5000/api/statistics/history?limit=50"

curl -X POST http://localhost:5000/api/statistics/refresh

• WebSocket support for real-time updates
• Predictive analytics for war outcomes
• Player performance metrics integration
• Discord webhook notifications for events
• Grafana dashboard integration
• Advanced filtering and search capabilities
• Data export (CSV, JSON, SQL)
• Authentication and rate limiting
• GraphQL API layer
• Caching layer (Redis)
• Docker containerization

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Copyright 2026 DataKnifeAI

Contributions are welcome! Please feel free to submit pull requests.

• Check that the API can reach https://api.helldivers2.dev
• Verify network connectivity and firewall settings
• Check logs for specific error messages
• If upstream API is down, endpoints with cache fallback will serve cached data (with 503 status if no cache exists)

• Ensure write permissions to the database directory
• Delete helldivers2.db and restart to rebuild the database

• Check logs for background scheduler errors
• Verify APScheduler is properly installed

• 404 Not Found: Resource doesn't exist or no data has been collected yet
• 503 Service Unavailable: Upstream API is down and no cached data is available (for endpoints with cache fallback)
• 500 Internal Server Error: Unexpected server error occurred