xg-model-building

xG Model Building

Important: PuckAPI does NOT have play-by-play data. The SDH database contains game-level data (scores, teams, odds, goalie starts) but no event-level shot data, coordinates, or play-by-play events.

Primary data source for xG: The NHL Stats API at api-web.nhle.com provides free play-by-play data with shot coordinates, event types, and strength state. No API key or credits required.

PuckAPI is useful for: Validating your xG model output against team-level stats (get_team_stats, 5 credits) and goalie stats (get_goalie_stats, 5 credits).

For user's own shot data CSV/JSON: skip external sources, work with the file directly.

You are an expert in hockey expected goals modeling. Your goal is to build a shot-level xG model that estimates the probability any given shot results in a goal, controlling for shot quality rather than shot volume.

When to Use

• User asks "how do I build an xG model"
• User wants to model shot probability or goal probability from play-by-play data
• User wants to compute xGF%, xGA, or expected goals for teams or players
• User asks about rebound detection, rush shot detection, or shot angle features
• User wants to replicate or improve upon MoneyPuck or Evolving Hockey xG methodology
• User asks about strength-state-specific (5v5, PP, SH, EN) goal models

When NOT to Use

• Using xG values that already exist -- to analyze teams with pre-built xG, see team-analysis or hockey-analytics
• Predicting game outcomes (win/loss) -- see model-building
• Evaluating goalie quality using xGA -- see goalie-analysis
• General feature engineering for non-xG features -- see feature-engineering

Data Sources

NHL Stats API (primary, free)

The NHL Stats API provides play-by-play event data for every game:

https://api-web.nhle.com/v1/gamecenter/{gameId}/play-by-play

Each play-by-play response includes shot events with:

• Event type (SHOT, GOAL, MISS, BLOCK)
• x/y coordinates (NHL coordinate system, feet, center ice = 0,0)
• Shot type (wrist, slap, snap, backhand, tip, deflection, wrap-around)
• Strength state (5v5, PP, SH, EN)
• Period and game time
• Shooter and goalie IDs