NHL data

Access and plan boundaries

NHL scores, standings, leaders, matchup data, player stats and player props have Free entry points. Full game play-by-play has a Pro floor. Modelled player and team features and odds can have different floors; use the plan badge on the exact endpoint rather than applying one route's access level to the rest of the sport.

See the current plan ladder and authentication guide.

History and coverage

NHL games, standings, box scores, xG, props and odds do not necessarily share one season range. Call the coverage endpoint and read each data type separately before selecting a model or backtest window.

curl "https://api.bigballsdata.com/v1/coverage?sport=ice_hockey" \
  -H "Authorization: Bearer $BBS_API_KEY"

Period linescores

Match and matchup responses can carry parallel linescore.home and linescore.away arrays. The first three entries are regulation periods; additional entries can represent overtime or the shootout. Label extra entries from the game status and period fields instead of assuming every fourth value means the same stage.

Expected goals

/v1/nhl/leaders exposes computed expected goals and goals above expected on the seasons where that model is populated. The current leaderboard is all-situations; do not relabel it as five-on-five. Treat null as unavailable rather than zero.

Goalie stats

The shared player-stat response includes skater and goalie fields. Goalie-only values such as save percentage, saves per game and goals against per game can be null for skaters and when the underlying box-score sample is empty. Check position and the response metadata before rendering a leaderboard.

Player props and freshness

/v1/nhl/players/:player_id/props supports the markets documented by its response, including shots on goal and goalie saves where available. Read freshness.status and data_as_of; an old line returned between seasons is not a promise of current market availability.

Odds

Historical opening and closing snapshots are separate from current match prices. Check the exact endpoint's plan badge, timestamp and coverage status before describing a price as live or using it as a closing line.

Regular season and postseason

Schedule and match routes use the same canonical match shape across season stages. The NHL matchup response can expose a stage value such as regular season, playoffs or preseason. Do not infer a playoff series score from standings rows or from one game's result unless the response explicitly includes that series object.

Identifiers and media

Join NHL resources on canonical ids, not player names. Team logo_url and player headshot_url are nullable; several NHL response paths do not have a complete media loader. Use initials or abbreviations when the URL is null. Never guess a league CDN path from a name or numeric id.