nhl-stats-api

A Promise-based client for the NHL stats API.

Features

• ⏳ Promise-based requests with fetch
• 🚫 Request cancellation via AbortSignal
• ✅ TypeScript types
• 🪶 Lightweight (less than 3kb)

Installation

Using npm:

$ npm i nhl-stats-api

Using yarn:

$ yarn add nhl-stats-api

Getting started

Basic usage example:

import { nhlStatsApi } from "nhl-stats-api";

nhlStatsApi.getTeams().then((teams) => {
  // ...
});

nhlStatsApi.getPlayer({ id: 8478483 }).then((player) => {
  // ...
});

...or, with async/await:

import { nhlStatsApi } from "nhl-stats-api";

const teams = await nhlStatsApi.getTeams();
const player = await nhlStatsApi.getPlayer(8478483);

Canceling requests

All endpoints support request cancellation by passing an AbortSignal to the options parameter (the last parameter for each endpoint).

const controller = new AbortController();
const signal = controller.signal;

nhlStatsApi.getPlayer(8478483, { signal });

controller.abort();

Endpoints

• Conferences
• Divisions
• Franchises
• Players
• Seasons
• Teams

Conferences

getConferences

Returns an array of all active conferences. For inactive conferences, use getConferenceById.

nhlStatsApi.getConferences();

getConferenceById

Returns a single conference. Requires the ID of the conference. This can be used to retrieve inactive conferences (e.g. ID 7 for the World Cup of Hockey).

nhlStatsApi.getConferenceById(6);

Divisions

getDivisions

Returns an array of all active divisions. For inactive divisions, use getDivisionById.

nhlStatsApi.getDivisions();

getDivisionById

Returns a single division. Requires the ID of the division. This can be used to retrieve inactive divisions (e.g. ID 13 for the Patrick division).

nhlStatsApi.getDivisionById(17);

Franchises

getFranchises

Returns an array of all franchises, including inactive ones.

nhlStatsApi.getFranchises();

getFranchiseById

Returns a single franchise. Requires the ID of the franchise.

nhlStatsApi.getFranchiseById(5);

Players

getPlayerById

Returns a single player. Requires the ID of the player.

nhlStatsApi.getPlayer(8478483);

getPlayerStats

Returns an array of stats or stat rankings for a player. Requires the ID of the player and the desired stats type.

nhlStatsApi.getPlayerStats(8478483, "statsSingleSeason");

Stats types

Below is the list of valid type values. Most types have both regular season and playoff-only versions.

• "byDayOfWeek" - Stats split by day of the week.
• "byDayOfWeekPlayoffs"
• "byMonth" - Stats split by month.
• "byMonthPlayoffs"
• "careerRegularSeason" - Total career statistics.
• "careerPlayoffs"
• "gameLog" - Stats split by individual game.
• "playoffGameLog"
• "goalsByGameSituation" - Number of goals scored by the player, by game situation. For goalies, this appears to be the number of goals scored against them.
• "goalsByGameSituationPlayoffs"
• "homeAndAway" - Stats split between home and away games.
• "homeAndAwayPlayoffs"
• "regularSeasonStatRankings" - Where a player ranks vs. the rest of the league in each stat.
• "playoffStatRankings"
• "statsSingleSeason" - Single season statistics.
• "statsSingleSeasonPlayoffs"
• "vsConference" - Conference stats split.
• "vsConferencePlayoffs"
• "vsDivision" - Division stats split.
• "vsDivisionPlayoffs"
• "vsTeam" - Stats split by opposing team.
• "vsTeamPlayoffs"
• "winLoss" - Stats split by W/L/OT.
• "winLossPlayoffs"
• "yearByYear" - Stats split by year. Can include data from leagues besides the NHL (e.g. GTHL, OHL, etc.).
• "yearByYearPlayoffs"
• "yearByYearRank" - Player ranks in each stat, split by year. Unlike year-by-year stats, this only includes NHL data.
• "yearByYearPlayoffsRank"

Filtering by season

By default, stats will always be for the current season. To request a different season, use the season prop of the options parameter. Note that this does not affect some stat types (e.g. career, year-by-year, etc.).

nhlStatsApi.getPlayerStats(8478483, "statsSingleSeason", {
  season: "20172018",
});

Finding a player's ID

You can find the ID of a player a couple of different ways. Using the API, you can get the roster of the team the player plays (or played) for and get their ID from that.

Alternatively, you can find a player's ID via their NHL.com profile. The number at the end of the URL will be their ID. For example, if you were to go to Mike Bossy's profile, the URL would be:

https://www.nhl.com/player/mike-bossy-8445611

So, his player ID is 8445611.

Seasons

getSeasons

Returns an array of all NHL seasons, past and present.

nhlStatsApi.getSeasons();

getSeasonById

Returns a single season. Requires the ID of the season. Alternatively, "current" can be used as the ID to get information on the most recent season of play.

nhlStatsApi.getSeason("20172018");
nhlStatsApi.getSeason("current");

Teams

getTeams

Returns a list of all active teams. For inactive teams, use getTeamById.

nhlStatsApi.getTeams();

getTeamById

Returns a single team. Requires the ID of the team. This can be used to retrieve inactive teams (e.g. ID 11 for the Atlanta Thrashers).

nhlStatsApi.getTeamById(10);

getTeamRoster

Returns an array containing the specified team's roster. Requires the ID of the team.

nhlStatsApi.getTeamRoster(10);

Full team roster

By default, the return value only includes players on the team's active NHL roster. To request a team's full roster, including inactive, injured, and minor league players, use the fullRoster prop of the options parameter.

nhlStatsApi.getTeamRoster(10, { fullRoster: true });

Filtering by season

To request a different season's roster, use the season prop of the options parameter.

nhlStatsApi.getTeamRoster(10, { season: "20172018" });

getTeamStats

Returns the regular season stats and stat rankings for a team. Requires the ID of the team.

nhlStatsApi.getTeamStats(10);

Filtering by season

By default, stats will always be for the current season. To request a different season, use the season prop of the options parameter.

nhlStatsApi.getTeamStats(10, { season: "20172018" });

Acknowledgements

Drew Hynes for his incredible work documenting the NHL API.

Disclaimer: NHL and the NHL Shield are registered trademarks of the National Hockey League. NHL and NHL team marks are the property of the NHL and its teams. © NHL 2023. All Rights Reserved.