How to Retrieve Player Stats from the NHL's undocumented REST API

It's that time of year again. Summer is coming to an end, Autumn is around the corner, and the NHL season is about to begin.

What better time to play around with the NHL's undocumented API? After some searching online and some trial and error I've managed to send an AJAX request and retrieve all kinds of NHL related stats from the semi-secret NHL API.

Let's take a look at how we can retrieve individual player stats from the API.

We will retrieve basic team information, the team's complete roster, and the ID number of individual players which will allow us to access their individual stats.

First, let's look at the root API endpoint:

https://statsapi.web.nhl.com/api/v1/

The root URL will result in an 404 error. If we tack /teams on to the URL endpoint we can retrieve basic information about all the NHL franchises including the team's first year in the league, conference, division, and information about the team's stadium.

The API endpoint to retrieve franchise data and the JSON returned:

https://statsapi.web.nhl.com/api/v1/teams

If we open one of the objects containing franchise data we see the following:

The object contains the properties id and link which contains the API endpoint for the New York Rangers' team data and also their team id number. The direct endpoint to access New York Rangers team data is https://statsapi.web.nhl.com/api/v1/teams/3. Now that we have the API endpoint for the franchise we can send a request that retrieves the roster of that team which will in turn allow us to access individual player stats by retrieving their ID's.

Sending a request to retrieve roster data and the JSON returned:

https://statsapi.web.nhl.com/api/v1/teams/3/roster

As you can see, the roster API endpoint returns data containing information about every player on the team. If we open the 11th element of the array we access Mika Zibanejad's data which includes his ID number and the API endpoint used to retrieve his individual stats and information.

Sending a request to retrieve Mika Zibanejad's individual data and the JSON returned:

https://statsapi.web.nhl.com/api/v1/people/8476459

This request will give us Mika Zibanejad's pedigree information such as height, weight, hometown, age, etc... But what if we want to retrieve his stats from the 2018-2019 season?

The API has a stats query that can accept a variety of values that return stats, and a season query specifying which season we want to retrieve data for. If we want to access single season stats for the 2018-2019 year we can do so by passing stats the value statsSingleSeason and season the value 20182019.

The complete endpoint for retrieving Zibanejad's stats and the returned JSON:

https://statsapi.web.nhl.com/api/v1/people/8476459/stats?stats=statsSingleSeason&season=20182019

The request returns a stats array that contains another array called splits. If we open up the 0th element of the splits array, which contains the property season and the value "20182019" we can see all kinds of stats from the 2018-2019 season:

There you have it. We have successfully retrieved Mika Zibanejad's information as well as his individual stats from the 2018-2019 year. Due to lack of documentation on the NHL's part it can be a little tedious finding and retrieving a player's stats from the API.

The easiest way to find any player's stats is to walk your way through the team and roster endpoints, retrieve the id and link for that particular player, and then use the people query or the stats query to send a request for his information and stats. The NHL does a terrible job when it comes to documentation, but the API is active and contains up-to-date data on any player in the league. There are a myriad of cool projects a developer can pursue with this data including comparing team or players stats in a web app, data visualization with D3.js, or even diving deeper into hockey statistics by using the data from the API to calculate more complex stats such as Corsi stats.

I have created a Github repository with the example code I used to write this article and it can be viewed here. My example uses React, Redux, and the Axios library and can be used as a starting off point for your own NHL stats related project.

I have also built this little web app showing example API calls and the data returned.

This concludes my article on using Javascript to fetch stats from the hockey Gods.