sports-schedule

Description

A Python tool to fetch sports schedules directly from APIs. Supports MLB, NHL, and PWHL team schedules with JSON output format.

Features

• Fetch NHL game schedules directly from the NHL API (configurable date range, default 28 days)
• Fetch MLB game schedules directly from the MLB API (configurable date range, default 28 days)
• Fetch PWHL game schedules directly from the PWHL API
• Process MLB team names using team codes
• Output JSON format for easy integration
• Configurable timezone support
• Configuration file support for easy team and API management
• Sport enable/disable controls - turn individual sports on/off
• Configurable PWHL season_id for when seasons change
• Automatic deduplication to prevent duplicate events
• Organized configuration structure with all sport settings grouped together

Configuration

The script supports a YAML configuration file (config.yaml) for easy management of teams and settings. The configuration is organized with all sport-specific settings grouped together for better maintainability.

Key configuration options:

• Sport Enable/Disable: Control which sports to process (MLB, NHL, PWHL)
• Teams: Pre-configure teams for each sport
• API Settings: Configure base URLs, keys, and date ranges per sport
• Filtering: Control which game statuses to skip per sport
• Output Settings: Default file names, timezone, and iCal options
• Global Settings: Logging and global filtering options

Command line arguments take precedence over configuration file values.

Usage

python generate_sports_schedule.py \
  --nhl-teams team1 team2 \
  --mlb-teams team1 team2 \
  --pwhl-teams team1 team2 \
  --teams-file mlb_teams.json \
  --output-json sports.json \
  --verbose

Examples

Note: Sports are enabled/disabled in the configuration file using sports.{sport}.enabled. Command line arguments only override team lists and other settings.

Override teams for Bruins games (NHL must be enabled in config)

python generate_sports_schedule.py --nhl-teams Bruins --output-json bruins.json

Override teams for Red Sox games (MLB must be enabled in config)

python generate_sports_schedule.py --mlb-teams "Boston Red Sox" --output-json redsox.json

Override teams for multiple sports (both NHL and MLB must be enabled in config)

python generate_sports_schedule.py --nhl-teams Bruins --mlb-teams "Boston Red Sox" --output-json boston_sports.json

Override teams for all three sports (all must be enabled in config)

python generate_sports_schedule.py --nhl-teams Bruins --mlb-teams "Boston Red Sox" --pwhl-teams "Boston Fleet" --output-json all_boston_sports.json

Using configuration file

# With teams pre-configured in config.yaml
python generate_sports_schedule.py --output-json my_sports.json

# Override specific config values
python generate_sports_schedule.py --config my_config.yaml --pwhl-teams "Boston Fleet"

Disabling sports in configuration

You can disable individual sports by setting their enabled flag to false:

sports:
  mlb:
    enabled: false  # This will disable MLB processing
  nhl:
    enabled: true   # NHL will still be processed
  pwhl:
    enabled: true   # PWHL will still be processed

When a sport is disabled, the script will log that it's skipping that sport and only process the enabled ones.

Output Formats

JSON Output

The tool generates a JSON file with this structure:

{
  "tasks": [
    {
      "name": "Bruins at Rangers - 19:00",
      "date": "2025-09-23",
      "time": "19:00",
      "location": "Madison Square Garden",
      "url": "https://www.nhl.com/gamecenter/2025010018",
      "source": "nhl_api"
    }
  ]
}

MLB Teams File Format

The mlb_teams.json file contains detailed team information in this format:

{
  "Boston Red Sox": {
    "teamName": "Red Sox",
    "shortName": "Boston",
    "clubName": "Red Sox",
    "locationName": "Boston",
    "abbreviation": "BOS",
    "id": 111
  }
}

Configuration File Structure

The configuration file uses YAML format with a clean, organized structure where all sport-specific settings are grouped together:

# Output settings
output:
  json_file: "sports.json"
  timezone: "America/New_York"
  ical:
    enabled: true  # Set to true to enable iCal output
    file: "sports.ics"
    calendar_name: "Sports Schedule"
    calendar_description: "Sports games and events"

# Sport configurations - each sport has all its settings grouped together
sports:
  mlb:
    enabled: true  # Set to false to disable MLB processing
    teams: ["Boston Red Sox"]
    teams_file: "mlb_teams.json"  # JSON file for team code mapping
    api:
      base_url: "http://statsapi.mlb.com/api/v1"
      date_range_days: 28  # Default days to look ahead
    filtering:
      skip_statuses: ["Final", "Game Over"]
  
  nhl:
    enabled: true  # Set to false to disable NHL processing
    teams: ["Bruins", "Oilers", "Jets", "Canadiens"]
    api:
      base_url: "https://api-web.nhle.com/v1"
      date_range_days: 28  # Default days to look ahead
    filtering:
      skip_statuses: []  # NHL doesn't have specific skip statuses
  
  pwhl:
    enabled: true  # Set to false to disable PWHL processing
    teams: ["Boston Fleet"]
    api:
      season_id: "5"  # Current PWHL season - update this when it changes!
      base_url: "https://lscluster.hockeytech.com/feed"
      key: "446521baf8c38984"
      client_code: "pwhl"
    filtering:
      skip_statuses: ["Final", "Final OT", "Final SO"]

# Global settings
global:
  filtering:
    skip_completed_games: true  # Skip completed games across all sports
  
  logging:
    level: "INFO"  # DEBUG, INFO, WARNING, ERROR
    verbose: false

Requirements

Python Version

• Python 3.9+ (required for zoneinfo module)

Dependencies

Install dependencies using one of these methods:

Option 1: Using pip

pip install -r requirements.txt

Option 2: Using conda

conda env create -f environment.yaml
conda activate sports-schedule

Required Packages

• requests>=2.25.0 - For HTTP requests to sports APIs
• PyYAML>=6.0 - For parsing configuration files
• icalendar>=5.0.0 - For generating iCal calendar files
• zoneinfo - For timezone handling (built into Python 3.9+)

Untested Note: If using Python < 3.9, you'll need to install backports.zoneinfo:

pip install backports.zoneinfo

Utilities

Generate MLB Teams File

The generate_mlb_teams.py script creates an updated mlb_teams.json file from the MLB API teams data:

python generate_mlb_teams.py

This script:

• Reads teams.json (from MLB API)
• Filters for active Major League Baseball teams
• Creates mlb_teams.json with detailed team information
• Supports both old and new file formats automatically

License

MIT