nhl-analytics

NHL Analytics: Multi-Season Longitudinal Panel Dataset (2013–2026)

Dataset Description

This dataset provides comprehensive, multi-season panel data for the National Hockey League (NHL), spanning over 17,000 games, 600,000 player-game appearances, and millions of play-by-play event coordinates from 2013 to the present day.

Unlike fragmented yearly CSV dumps, this repository organizes NHL data by domain entity and data type into high-performance Apache Parquet tables with standardized schemas, UTC timestamps, and validated primary keys.

Automated daily GitHub Actions workflows incrementally append and update incoming game records from the NHL Edge API.

Dataset Structure

1. games.parquet (Game Master Panel)

• Unit of Observation: One row per game (game_id).
• Columns: game_id, season, game_date, time_start, home_team, away_team, home_team_id, away_team_id, home_score, away_score, period_ending, winning_team.

2. team_box.parquet (Team-Game Box Scores)

• Unit of Observation: One row per team per game (game_id, team).
• Columns: game_id, season, game_date, team, is_home, goals, shots, hits, shots_blocked, goals_pp, pim, takeaways, giveaways, faceoff_win_pct, win.

3. player_box.parquet (Individual Player Performance)

• Unit of Observation: One row per player per game (game_id, player_id).
• Columns: game_id, season, game_date, player_id, player_name, team, position, sweater_number, toi, goals, assists, points, plus_minus, pim, hits, sog, blocked_shots, faceoff_pct, saves, shots_against, save_pct.

4. odds.parquet (Betting Closing Lines)

• Unit of Observation: Closing market odds per game.
• Columns: game_id, game_date, home_team, away_team, odds_description, home_odds, away_odds, betting_partner, last_updated_utc.

5. hit_impact.parquet (Physicality & Downstream Sequences)

• Unit of Observation: Derived physical contact sequences and puck recovery transitions.
• Columns: game_id, elapsed_sec, focal_team_abbrev, hit_for_O, hit_for_D, hit_for_N, hit_against_O, hit_against_D, hit_against_N, shot_for, shot_against, takeaway, giveaway, block_for, block_against.

6. playbyplay/ (Event Microdata Partitioned by Season)

• Unit of Observation: Granular play-by-play events (game_id, event_id).
• Partitioning: Directory partitioned by season=YYYYYYYY/pbp_YYYYYYYY.parquet.

7. playbyplay_player.parquet (Game Roster & Participating Players)

• Unit of Observation: One row per skater/goaltender present on the official game sheet (game_id, player_id).
• Columns: game_id, season, player_id, team, sweater_number, position, first_name, last_name, headshot.

8. shifts.parquet (Shift-Level Tracking)

• Unit of Observation: Individual on-ice player shift (shift_id).
• Columns: shift_id, game_id, player_id, season, team, player_name, period, shift_number, start_time, end_time, duration, type_code, detail_code, event_number, event_description, event_details.

Quickstart & Query Examples

A. Zero-Install Streaming SQL with DuckDB

-- Query directly from Hugging Face over HTTP without local downloads
SELECT 
    season, 
    home_team, 
    COUNT(*) AS total_home_games,
    ROUND(AVG(home_score), 2) AS avg_goals_scored
FROM 'hf://datasets/jjerlee/nhl-analytics/data/games.parquet'
WHERE season >= 20212022
GROUP BY season, home_team
ORDER BY season DESC, avg_goals_scored DESC;

B. Python (polars or pandas)

import polars as pl

url = "https://huggingface.co/datasets/jjerlee/nhl-analytics/resolve/main/data/team_box.parquet"
df_teams = pl.read_parquet(url)
print(df_teams.filter(pl.col("team") == "MTL").tail(10))

C. Hugging Face datasets

from datasets import load_dataset

dataset = load_dataset("jjerlee/nhl-analytics", "games", split="train")
print(dataset[0])

Data Source & Automation

Data is scraped and transformed from the official NHL Edge API and market data providers. Maintained via the NHL-Analytics (Rinklytics) open-source project.