Nick Kinlen

Front-end Developer | NYC

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.

Tags

Comments

September 18th, 2019

Jeez dude, awesome detective work here! I miss watching hockey – I was into the NHL around 2008, when the Red Wings won the Stanley Cup (I’m from Detroit, so it was a big deal, having been the first cup since Yzerman IIRC). Might have to start watching again this season.

Do you think they’ll be shutting this down or otherwise locking us out anytime soon? Any advice on how to programatically map out the endpoints? (It seems like they give links for certain endpoints for more data, at least, so it seems possible, but I’m curious if some are missing/incomplete). In any case, great stuff man! Keep 'em coming! :grin:

September 20th, 2019

Thanks for the positive feedback.

I played around with this API about a year ago briefly and it appears to have stayed the same. I’m pretty sure they’re not doing away with it any time soon. I found some basic endpoints on Github and just started playing with the API and digging around. I’m not sure this API was intended for public use, as far as I know there is no official documentation.

As far as mapping out the endpoints I’m not sure. I’m a big Rangers fan and I’m working on a little project with this API that compares the Rangers top rookie (Kaapo Kakko) and the Devils top rookie (Jack Hughes) who are the number one and number two draft picks. I’m gonna compare stats, maybe do some data viz stuff with D3, etc… comparing the two players.

I’m sure I’ll get more familiar with the API as I work on this project. Maybe I’ll write another article in a few weeks after I discover/work with more endpoints.

Get back into hockey the Wings are gonna make a comeback in the next couple of years.:+1:

Topics of interest