The Hockey Game Bot is a Python application that leverages the NHL API and hockey statistics sites to send real-time game updates to social media platforms. The bot provides fans with a comprehensive view of NHL games including live events, statistics, and advanced analytics - all in one convenient place.
New in v2.0: Real-time monitoring dashboard with comprehensive tracking of bot health, API performance, and game statistics.
- Live game state tracking - Current score, period, time remaining
- Comprehensive event counting - Goals, penalties, shots, hits, blocks, and more
- API performance monitoring - Success/failure rates, call tracking
- Bot health monitoring - Status, uptime, errors, system health
- Social media activity - Post counts, timestamps, preview post status
- Auto-refresh dashboard - Updates every 2 seconds
- Network accessible - View from any device on your local network
- Pre-game messages - Game time, season series, team stats, officials
- Live game events - Goals, penalties, period starts, shots on goal
- Post-game reports - Final stats, three stars, advanced analytics
- Day-after analysis - Season performance charts and trends
Currently supports Bluesky with automatic post tracking and monitoring.
The dashboard provides real-time visibility into your bot:
┌─────────────────────────────────────────────────────────┐
│ 🏒 Hockey Bot Dashboard │
│ Status: ● RUNNING Last Update: 2s ago │
├─────────────────────────────────────────────────────────┤
│ │
│ GAME INFORMATION │
│ ┌──────────────────────────────────────────────────┐ │
│ │ NYR @ NJD │ │
│ │ 2 3 │ │
│ └──────────────────────────────────────────────────┘ │
│ Period: 2nd Time: 08:42 │
│ Game ID: 2025020176 State: LIVE │
│ │
│ EVENTS: Goals (5) | Penalties (4) | Shots (47) │
│ API CALLS: 178 (98.9% success) │
│ POSTS SENT: 12 │
└─────────────────────────────────────────────────────────┘
- Python 3.11 or higher (for optimal performance and security)
- Basic understanding of virtualenv and pip
- A server or computer that can run continuously (Raspberry Pi, AWS EC2, local machine, etc.)
-
Clone the repository
git clone https://github.com/mattdonders/hockeygamebot.git cd hockeygamebot -
Create and activate virtual environment
python3 -m venv .env source .env/bin/activate # On Windows: .env\Scripts\activate
-
Install dependencies
pip install -r requirements.txt
-
Configure your bot
cp config-sample.yaml config.yaml # Edit config.yaml with your team and API credentials -
Run the bot
python -m hockeygamebot --config config.yaml
-
Access the dashboard
- The dashboard server starts automatically with the bot
- Open your browser to:
http://localhost:8000/dashboard.html - From phone/tablet:
http://YOUR_COMPUTER_IP:8000/dashboard.html
Option 1: Auto-start with Bot (Recommended)
- Dashboard starts automatically when you run the bot
- Access at
http://localhost:8000/dashboard.html
Option 2: Standalone Dashboard Server
- Useful for viewing status even after bot exits
- Run:
./start-dashboard.sh(from project directory) - Runs in background, survives bot restarts
| Section | What It Shows |
|---|---|
| Game Information | Live score, teams, period, time, venue, game state |
| Bot Statistics | Uptime, live loops processed, start time |
| System Health | Bot status (RUNNING/SLEEPING/ERROR), error count, health checks |
| Game Events | Total events, goals, penalties, shots, saves, hits, blocks, etc. |
| API Performance | Total API calls, success/failure rates, success percentage |
| Social Media | Posts sent, last post time, preview post status |
-
Find your computer's IP address:
# Mac ipconfig getifaddr en0 # Linux hostname -I | awk '{print $1}'
-
Open browser on phone and go to:
http://YOUR_COMPUTER_IP:8000/dashboard.html -
Bookmark it for easy access during games!
default:
team_name: "New Jersey Devils"
bluesky:
prod:
account: "your-handle.bsky.social"
password: "your-app-password"
debug:
account: "debug-handle.bsky.social"
password: "your-debug-password"
script:
live_sleep_time: 30 # Seconds between live game checkspython -m hockeygamebot [OPTIONS]
Options:
--config CONFIG Path to config file (default: config.yaml)
--date DATE Override game date (format: YYYY-MM-DD)
--nosocial Log messages instead of posting to social media
--console Log to console instead of file
--debug Enable debug logging
--debugsocial Use debug social accounts for testing
-h, --help Show help messageExamples:
# Normal operation
python -m hockeygamebot
# Testing mode (no social posts, console logging)
python -m hockeygamebot --nosocial --console
# Check specific date
python -m hockeygamebot --date 2025-10-30
# Debug mode with debug accounts
python -m hockeygamebot --debug --debugsocialhockeygamebot/
├── core/
│ ├── models/
│ │ ├── clock.py # Game clock tracking
│ │ ├── game_context.py # Centralized game state
│ │ └── team.py # Team data models
│ ├── events/ # Event handlers
│ ├── integrations/ # External API integrations
│ ├── charts.py # Chart generation
│ ├── final.py # Post-game logic
│ ├── live.py # Live game processing
│ ├── preview.py # Pre-game messages
│ ├── rosters.py # Roster management
│ └── schedule.py # Game scheduling and API calls
├── socials/
│ ├── bluesky.py # Bluesky integration
│ └── social_state.py # Social post tracking
├── utils/
│ ├── config.py # Configuration management
│ ├── others.py # Utility functions
│ ├── retry.py # Retry decorator
│ ├── sessions.py # Session management
│ ├── team_details.py # Team information
│ └── status_monitor.py # Dashboard monitoring (NEW)
├── resources/ # Fonts and static assets
├── images/ # Generated charts
├── logs/ # Log files
├── dashboard.html # Real-time dashboard UI (NEW)
├── status.json # Live bot status data (NEW)
├── hockeygamebot.py # Main application
├── config.yaml # Configuration file
└── requirements.txt # Python dependencies
- Game time announcement - Time, venue, broadcast info, hashtags
- Season series - Team records against each other this season
- Team statistics - Pre-game stat comparison chart
- Officials - Referees and linesmen assigned to the game
- Period starts - On-ice players, opening faceoff winner
- Goals - Real-time alerts with scorer, assists, and video highlights
- Penalties - Penalty description with power play stats
- Shots and saves - Notable saves and shot attempts
- Intermission reports - Period stats and team performance
- Final score - Game result with basic stats
- Three stars - Game's three stars (if available)
- Advanced analytics - Charts from Natural Stat Trick
- Video highlights - Game recap and condensed game videos
- Season performance charts - Team stats vs. league average
- Last 10 games trends - Recent performance analysis
Dashboard shows "Error loading status.json"
- Verify the bot is running
- Check that
status.jsonexists in the project directory - Ensure the web server is running (auto-starts with bot)
- Try refreshing the browser (Ctrl/Cmd + R)
Dashboard not updating
- Check browser console (F12) for JavaScript errors
- Verify bot is in the game loop (not sleeping for hours)
- Check
status.jsonfile modification time - Status updates every time the game loop runs
Can't access dashboard from phone
- Ensure phone is on same WiFi network
- Verify firewall isn't blocking port 8000
- Check your computer's IP address hasn't changed
- Try
http://COMPUTER_IP:8000/dashboard.html
Web server logs cluttering console
- The bot uses a silent HTTP handler to suppress logs
- If still seeing logs, ensure you're using the latest version
Bot not starting
- Check Python version:
python --version(need 3.10+) - Verify all dependencies installed:
pip install -r requirements.txt - Check config.yaml for syntax errors
- Review logs in
logs/directory
No social posts appearing
- Verify Bluesky credentials in config.yaml
- Check if running with
--nosocialflag (testing mode) - Review logs for authentication errors
- Ensure account isn't rate-limited
Bot not finding games
- Check team name in config.yaml matches NHL team name
- Try
--date YYYY-MM-DDto test with specific date - Verify team has a game on the target date
- Check NHL API is accessible
API calls showing high failure rate
- Network connectivity issues - check your internet
- NHL API may be temporarily down
- Rate limiting - bot automatically retries failed calls
- Check logs for specific error messages
To automatically start the bot daily (e.g., 9:00 AM):
crontab -eAdd this line:
0 9 * * * cd /path/to/hockeygamebot && ./.env/bin/python -m hockeygamebot
Create /etc/systemd/system/hockeygamebot.service:
[Unit]
Description=Hockey Game Bot
After=network.target
[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/hockeygamebot
ExecStart=/path/to/hockeygamebot/.env/bin/python -m hockeygamebot
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.targetEnable and start:
sudo systemctl enable hockeygamebot
sudo systemctl start hockeygamebot
sudo systemctl status hockeygamebot- Never commit config.yaml - Contains API credentials
- Use app passwords - Don't use your main Bluesky password
- Firewall dashboard port - Only expose to trusted networks
- Rotate credentials - Change passwords periodically
- Monitor access - Check dashboard access logs if concerned
- Raspberry Pi users: Works great on Pi 4 with 2GB+ RAM
- AWS/Cloud: t2.micro instance is sufficient for single team
- Network: Stable internet connection is critical for API calls
- Storage: ~500MB for application + logs over season
- Dashboard: Minimal resource usage, designed for efficiency
Contributions are welcome! Whether it's bug reports, feature requests, or code contributions:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
We use SemVer for versioning. For available versions, see the tags on this repository.
Matt Donders - mattdonders.com
Special thanks to everyone who has helped test, provide feedback, and contribute data:
- Natural Stat Trick - naturalstattrick.com
- Hockey Stat Cards - hockeystatcards.com
- Daily Faceoff - dailyfaceoff.com
- Hockey Reference - hockey-reference.com
- Scouting the Refs - scoutingtherefs.com
- NHL API Documentation - gitlab.com/dword4/nhlapi
This project is open source and available for personal use. Please respect NHL data usage policies and rate limits.
If you enjoy using this bot and want to support development:
- ⭐ Star this repository
- 🐛 Report bugs and issues
- 💡 Suggest new features
- 📢 Share with other hockey fans
Built with ❤️ for hockey fans by hockey fans