Pull Your First NHL Data from the Public NHL API

Not every sport hands you a friendly Python library to hide behind. Sometimes you talk to a raw web API and shape the JSON yourself - and honestly, that's the more valuable skill, because it works for almost any data source on the internet, not just this one. The NHL's public API is the perfect place to learn it: no key, no signup, no token, no nonsense. We'll pull the current standings over a polite HTTP session, flatten the nested JSON into a tidy DataFrame, work out each team's goal differential, and chart it as a diverging bar plot - and you'll come out the other side able to do the same dance with most APIs you meet.

This builds on how to read API documentation, so you already know how to find an endpoint and read a response. The data comes from the NHL public API (api-web.nhle.com), retrieved June 2026.

1. Open a polite session

   We could call requests.get directly, but we'll use a session instead, configured to behave like a well-mannered browser. A polite session sends a normal User-Agent header, identifies where the request is coming from with a Referer, and automatically retries with backoff if the server returns a temporary error like 429 (too many requests) or 503 (service unavailable). These are the habits that keep a free public API open for everyone.

   import matplotlib.pyplot as plt
   import pandas as pd
   
   session = sdt.polite_session(referer="https://www.nhl.com/")
   resp = session.get("https://api-web.nhle.com/v1/standings/now", timeout=30)
   resp.raise_for_status()
   teams = resp.json()["standings"]

   The endpoint /v1/standings/now returns the standings as of today. raise_for_status() turns any HTTP error into a clean Python exception so a bad response fails loudly instead of silently. And resp.json()["standings"] reaches into the response and pulls out the list of team objects - the part we actually want.

2. Understand the nested shape

   Here's the thing that trips up newcomers to JSON APIs: the values aren't always plain strings. The NHL serves names as little objects keyed by language, because the league is bilingual. A team's name arrives looking like {"default": "Colorado Avalanche", "fr": "Avalanche du Colorado"}. To get the English string you have to reach one level deeper, into the "default" key. That single idea - teamName["default"] - is the crux of shaping this data.

   # Each team's name and abbreviation arrive as language objects:
   #   t["teamName"]  ->  {"default": "Colorado Avalanche", "fr": ...}
   # so we reach into ["default"] to get the plain English string.

   Most other fields - wins, losses, points, goals - are plain numbers and can be read directly. It's mainly the text fields that hide behind ["default"].

3. Flatten the JSON into a DataFrame

   Now we walk the list of teams and build one clean dictionary per team, picking out exactly the fields we want and unwrapping the language objects as we go. Wrapping that list of dictionaries in pd.DataFrame(...) gives us a proper table.

   df = pd.DataFrame([{
       "Team": t["teamName"]["default"],
       "Abbr": t["teamAbbrev"]["default"],
       "Division": t["divisionName"],
       "GP": t["gamesPlayed"],
       "W": t["wins"],
       "L": t["losses"],
       "OTL": t["otLosses"],
       "PTS": t["points"],
       "GF": t["goalFor"],
       "GA": t["goalAgainst"],
   } for t in teams])

   This is a list comprehension building a list of dictionaries: for each team t, make a flat record. The two text fields use ["default"]; everything else reads straight across. The result is a familiar, rectangular DataFrame - the shape every later step expects.

4. Compute goal differential

   Goal differential - goals scored minus goals allowed - is the single most honest one-number summary of a hockey team's season. A new column is just arithmetic on two existing ones, and then we sort so the best teams sit at the top.

   df["Diff"] = df["GF"] - df["GA"]
   df = df.sort_values("Diff", ascending=False).reset_index(drop=True)

   reset_index(drop=True) renumbers the rows 0, 1, 2, … after the sort so the index reads as a clean ranking instead of the scrambled original order. It's a small touch that makes the printed table much easier to read.

5. Look at the best and worst

   Let's print a slice of the table to confirm the data and the differential make sense.

   print(f"Pulled {len(df)} teams. Best and worst by goal differential:")
   sdt.show_df(df[["Team", "GP", "PTS", "GF", "GA", "Diff"]], n=6)

   Top teams by goal differential

   Pulled 32 teams. Best and worst by goal differential:
                     Team  GP  PTS   GF   GA  Diff
   0   Colorado Avalanche  82  121  302  203    99
   1  Tampa Bay Lightning  82  106  290  231    59
   2  Carolina Hurricanes  82  113  296  240    56
   3         Dallas Stars  82  112  279  226    53
   4       Buffalo Sabres  82  109  288  241    47
   5       Minnesota Wild  82  104  272  240    32

   Thirty-two teams, exactly the size of the league - a good sanity check that we caught everyone. At the top sits the Colorado Avalanche with a goal differential of +99: 302 goals scored against just 203 allowed over 82 games, good for 121 points. That dominance over a full season is exactly what a +99 differential looks like, and the orderly drop-off behind them - Tampa Bay at +59, Carolina at +56, Dallas at +53 - tells you the parsing worked and the sort is correct.

6. Chart it as a diverging bar plot

   Goal differential is naturally two-sided: some teams are positive, some negative. A diverging bar chart - bars growing right from a center line for good teams, left for bad ones, colored differently on each side - is the perfect way to show that. We color positives in hockey blue and negatives in a warning red, sort ascending so matplotlib stacks the best team at the top, and draw a vertical line at zero as the dividing point.

   # A diverging bar chart: green for teams above zero, red for below.
   plot_df = df.sort_values("Diff")
   colors = [sdt.sport_color("hockey") if d >= 0 else sdt.SPORT_COLORS["baseball"]
             for d in plot_df["Diff"]]
   fig, ax = plt.subplots(figsize=(8, 8.4))
   ax.barh(plot_df["Abbr"], plot_df["Diff"], color=colors)
   ax.axvline(0, color="#20242B", linewidth=0.8)
   ax.set_title("NHL goal differential by team (most recent season)")
   ax.set_xlabel("goals for minus goals against")
   ax.tick_params(axis="y", labelsize=8)
   fig.savefig("goal_differential.png", dpi=144, bbox_inches="tight")

   

   The color list is built with a comprehension that checks each value's sign - blue if it's zero or positive, red if negative - so the chart paints itself correctly no matter which teams end up on which side. The zero line is the visual spine of the whole plot: every bar reaching right is a team that outscored its opponents, every bar reaching left is one that got outscored. You can read the league's pecking order in a single glance.

Troubleshooting