NAV
shell

NHL API

Welcome to the BALLDONTLIE NHL API, the best HOCKEY API on the planet. This API contains comprehensive NHL data. An API key is required. You can obtain an API key by creating a free account on our website. Read the authentication section to learn how to use the API key.

Take a look at our other APIs:

Join us on discord.

Account Tiers

There are three different account tiers which provide you access to different types of data. Visit our website to create an account for free.

Paid tiers do not apply across sports. The tier you purchase for NHL will not automatically be applied to other sports. You can purchase the ALL-ACCESS ($89.99/mo) tier to get access to every endpoint for every sport.

Read the table below to see the breakdown.

Endpoint Free ALL-STAR GOAT
Teams Yes Yes Yes
Players Yes Yes Yes
Games No Yes Yes
Standings No Yes Yes
Box Scores No Yes Yes
Player Season Stats No No Yes
Team Season Stats No No Yes
Player Stats Leaders No No Yes
Team Stats Leaders No No Yes

The feature breakdown per tier is shown in the table below.

Tier Requests / Min $USD / mo.
GOAT 600 39.99
ALL-STAR 60 9.99
Free 5 0

Authentication

To authorize, use this code:

curl "api_endpoint_here" -H "Authorization: YOUR_API_KEY"

Make sure to replace YOUR_API_KEY with your API key.

BALLDONTLIE uses API keys to allow access to the API. You can obtain an API key by creating a free account at our website

We expect the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: YOUR_API_KEY

Pagination

This API uses cursor based pagination rather than limit/offset. Endpoints that support pagination will send back responses with a meta key that looks like what is displayed on the right.

{
  "meta": {
    "next_cursor": 90,
    "per_page": 25
  }
}

You can use per_page to specify the maximum number of results. It defaults to 25 and doesn't allow values larger than 100.

You can use next_cursor to get the next page of results. Specify it in the request parameters like this: ?cursor=NEXT_CURSOR.

Errors

The API uses the following error codes:

Error Code Meaning
401 Unauthorized - You either need an API key or your account tier does not have access to the endpoint.
400 Bad Request -- The request is invalid. The request parameters are probably incorrect.
404 Not Found -- The specified resource could not be found.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You're rate limited.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Teams

Get All Teams

curl "https://api.balldontlie.io/nhl/v1/teams" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
        "id": 55,
        "full_name": "Philadelphia Flyers",
        "tricode": "PHI",
        "conference_name": "Eastern",
        "division_name": "Metropolitan"
    },
    {
        "id": 56,
        "full_name": "Anaheim Ducks",
        "tricode": "ANA",
        "conference_name": "Western",
        "division_name": "Pacific"
    },
    {
        "id": 57,
        "full_name": "Seattle Kraken",
        "tricode": "SEA",
        "conference_name": "Western",
        "division_name": "Pacific"
    },
    ...
  ]
}

This endpoint retrieves all teams.

HTTP Request

GET https://api.balldontlie.io/nhl/v1/teams

Query Parameters

Parameter Required Description
conference false Filter by conference name
division false Filter by division name

Get a Specific Team

curl "https://api.balldontlie.io/nhl/v1/teams/13" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": {
    "id": 13,
    "full_name": "San Jose Sharks",
    "tricode": "SJS",
    "conference_name": "Western",
    "division_name": "Pacific"
  }
}

This endpoint retrieves a specific team.

HTTP Request

GET https://api.balldontlie.io/nhl/v1/teams/:id

URL Parameters

Parameter Description
id Team ID

Team Season Stats

Get Season Stats for a Team

curl "https://api.balldontlie.io/nhl/v1/teams/61/season_stats?season=2024" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
      "value": 39,
      "name": "wins"
    },
    {
      "value": 36,
      "name": "losses"
    },
    {
      "value": 7,
      "name": "ot_losses"
    },
    {
      "value": 85,
      "name": "points"
    },
    {
      "value": 0.51829,
      "name": "points_pct"
    },
    {
      "value": 255,
      "name": "goals_for"
    },
    {
      "value": 82,
      "name": "games_played"
    },
    {
      "value": 255,
      "name": "goals_against"
    },
    {
      "value": 0,
      "name": "goal_differential"
    },
    {
      "value": 3.10975,
      "name": "goals_for_per_game"
    },
    {
      "value": 3.10975,
      "name": "goals_against_per_game"
    },
    {
      "value": 0.17619,
      "name": "power_play_percentage"
    },
    {
      "value": 0.803348,
      "name": "penalty_kill_percentage"
    },
    {
      "value": 28.58536,
      "name": "shots_for_per_game"
    },
    {
      "value": 29.89024,
      "name": "shots_against_per_game"
    },
    {
      "value": 0.535706,
      "name": "faceoff_win_percentage"
    }
  ]
}

This endpoint retrieves season statistics for a specific team.

HTTP Request

GET https://api.balldontlie.io/nhl/v1/teams/:id/season_stats

URL Parameters

Parameter Description
id Team ID

Query Parameters

Parameter Required Description
season true Returns stats for this season
postseason false If true, return postseason stats

Team Stats Leaders

Get Leaders for Team Stats

curl "https://api.balldontlie.io/nhl/v1/team_stats/leaders?season=2024&type=goals_for" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
        "team": {
            "id": 21,
            "full_name": "Winnipeg Jets",
            "tricode": "WPG",
            "conference_name": "Western",
            "division_name": "Central"
        },
        "name": "points",
        "value": 116,
        "season": 2024,
        "postseason": false
    },
    {
        "team": {
            "id": 36,
            "full_name": "Washington Capitals",
            "tricode": "WSH",
            "conference_name": "Eastern",
            "division_name": "Metropolitan"
        },
        "name": "points",
        "value": 111,
        "season": 2024,
        "postseason": false
    },
    ...
  ]
}

This endpoint retrieves team statistical leaders.

HTTP Request

GET https://api.balldontlie.io/nhl/v1/team_stats/leaders

Query Parameters

Parameter Required Description
season true Returns leaders for this season
type true The stat type to get leaders for
postseason false If true, return postseason leaders

Available Stat Types

The type parameter must be one of:

faceoff_win_percentage, shots_for_per_game, penalty_kill_percentage, goals_against_per_game, games_played, goals_for_per_game, goals_against, points_pct, points, power_play_percentage, shots_against_per_game, goals_for, wins, goal_differential, ot_losses, losses

Players

Get All Players

curl "https://api.balldontlie.io/nhl/v1/players?team_ids[]=61&seasons[]=2024" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
      {
          "id": 13,
          "first_name": "Jonathan",
          "last_name": "Quick",
          "full_name": "Jonathan Quick",
          "position_code": "G",
          "shoots_catches": "L",
          "height_in_inches": 73,
          "weight_in_pounds": 220,
          "birth_date": "1986-01-20",
          "birth_place": "Milford, CT, USA",
          "teams": [
              {
                  "id": 61,
                  "full_name": "New York Rangers",
                  "tricode": "NYR",
                  "conference_name": "Eastern",
                  "division_name": "Metropolitan",
                  "season": 2024
              }
          ]
      },
      {
          "id": 71,
          "first_name": "Calvin",
          "last_name": "de Haan",
          "full_name": "Calvin de Haan",
          "position_code": "D",
          "shoots_catches": "L",
          "height_in_inches": 73,
          "weight_in_pounds": 192,
          "birth_date": "1991-05-08",
          "birth_place": "Carp, ON, CAN",
          "teams": [
              {
                  "id": 61,
                  "full_name": "New York Rangers",
                  "tricode": "NYR",
                  "conference_name": "Eastern",
                  "division_name": "Metropolitan",
                  "season": 2024
              }
          ]
      },
      ...
  ],
  "meta": {
    "next_cursor": null,
    "per_page": 25
  }
}

This endpoint retrieves all players based on the provided filters.

HTTP Request

GET https://api.balldontlie.io/nhl/v1/players

Query Parameters

Parameter Required Description
cursor false The cursor for pagination
per_page false Number of results per page (max 100)
name false Filter by player name
player_ids false Filter by player IDs
team_ids false Filter by team IDs
seasons false Filter by seasons

Player Season Stats

Get Player Season Stats

curl "https://api.balldontlie.io/nhl/v1/players/35/season_stats?season=2024" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
        "value": 30,
        "name": "assists"
    },
    {
        "value": 32,
        "name": "even_strength_goals"
    },
    {
        "value": 54,
        "name": "even_strength_points"
    },
    {
        "value": 0,
        "name": "faceoff_win_pct"
    },
    {
        "value": 75,
        "name": "games_played"
    },
    ...
  ]
}

This endpoint retrieves season statistics for a specific player.

HTTP Request

GET https://api.balldontlie.io/nhl/v1/players/:id/season_stats

URL Parameters

Parameter Description
id Player ID

Query Parameters

Parameter Required Description
season true Returns stats for this season
postseason false If true, return postseason stats

Player Stats Leaders

Get Leaders for Player Stats

curl "https://api.balldontlie.io/nhl/v1/player_stats/leaders?season=2024&type=points" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
        "player": {
            "id": 155,
            "first_name": "Nikita",
            "last_name": "Kucherov",
            "full_name": "Nikita Kucherov",
            "position_code": "R",
            "shoots_catches": "L",
            "height_in_inches": 72,
            "weight_in_pounds": 180,
            "birth_date": "1993-06-16",
            "birth_place": "Maykop, RUS",
        },
        "name": "points",
        "value": 121,
        "season": 2024,
        "postseason": false
    },
    {
        "player": {
            "id": 267,
            "first_name": "Nathan",
            "last_name": "MacKinnon",
            "full_name": "Nathan MacKinnon",
            "position_code": "C",
            "shoots_catches": "R",
            "height_in_inches": 72,
            "weight_in_pounds": 200,
            "birth_date": "1995-08-31",
            "birth_place": "Halifax, NS, CAN",
        },
        "name": "points",
        "value": 116,
        "season": 2024,
        "postseason": false
    },
    ...
  ]
}

This endpoint retrieves player statistical leaders.

HTTP Request

GET https://api.balldontlie.io/nhl/v1/player_stats/leaders

Query Parameters

Parameter Required Description
season true Returns leaders for this season
type true The stat type to get leaders for
postseason false If true, return postseason stats

Available Stat Types

The type parameter must be one of:

goals, power_play_points, game_winning_goals, plus_minus, even_strength_points, shots_against, goals_against_average, games_played, goals_against, shots, games_started, short_handed_goals, short_handed_points, faceoff_win_pct, assists, save_pct, power_play_goals, time_on_ice_per_game, wins, ot_losses, overtime_goals, penalty_minutes, saves, points, even_strength_goals, shutouts, shooting_pct, time_on_ice, points_per_game, losses

Games

Get All Games

curl "https://api.balldontlie.io/nhl/v1/games?seasons[]=2024&team_ids[]=61" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
      {
          "id": 7,
          "season": 2024,
          "game_date": "2024-10-09",
          "start_time_utc": "2024-10-09T23:30:00.000Z",
          "home_team": {
              "id": 59,
              "full_name": "Pittsburgh Penguins",
              "tricode": "PIT",
              "conference_name": "Eastern",
              "division_name": "Metropolitan"
          },
          "away_team": {
              "id": 61,
              "full_name": "New York Rangers",
              "tricode": "NYR",
              "conference_name": "Eastern",
              "division_name": "Metropolitan"
          },
          "home_sog": 31,
          "away_sog": 40,
          "home_score": 0,
          "away_score": 6,
          "venue": "PPG Paints Arena",
          "game_state": "OFF",
          "period": 3,
          "postseason": false
      },
    ...
  ],
  "meta": {
    "next_cursor": null,
    "per_page": 25
  }
}

This endpoint retrieves all games based on the provided filters.

HTTP Request

GET https://api.balldontlie.io/nhl/v1/games

Query Parameters

Parameter Required Description
cursor false The cursor for pagination
per_page false Number of results per page (max 100)
team_ids false Filter by team IDs
dates false Filter by specific dates (YYYY-MM-DD)
seasons false Filter by seasons
postseason false Filter by postseason status
game_ids false Filter by specific game IDs

Standings

Get Team Standings

curl "https://api.balldontlie.io/nhl/v1/standings?season=2024&division=Atlantic" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
      {
          "team": {
              "id": 46,
              "full_name": "Toronto Maple Leafs",
              "tricode": "TOR",
              "conference_name": "Eastern",
              "division_name": "Atlantic"
          },
          "season": 2024,
          "conference_name": "Eastern",
          "division_name": "Atlantic",
          "games_played": 82,
          "points": 108,
          "regulation_wins": 41,
          "regulation_plus_ot_wins": 51,
          "wins": 52,
          "losses": 26,
          "ot_losses": 4,
          "points_pctg": 0.658537,
          "goals_for": 268,
          "goals_against": 231,
          "goal_differential": 37,
          "home_record": "27-13-1",
          "road_record": "25-13-3",
          "streak": "W5"
      },
      {
          "team": {
              "id": 22,
              "full_name": "Tampa Bay Lightning",
              "tricode": "TBL",
              "conference_name": "Eastern",
              "division_name": "Atlantic"
          },
          "season": 2024,
          "conference_name": "Eastern",
          "division_name": "Atlantic",
          "games_played": 82,
          "points": 102,
          "regulation_wins": 41,
          "regulation_plus_ot_wins": 45,
          "wins": 47,
          "losses": 27,
          "ot_losses": 8,
          "points_pctg": 0.621951,
          "goals_for": 294,
          "goals_against": 219,
          "goal_differential": 75,
          "home_record": "29-8-4",
          "road_record": "18-19-4",
          "streak": "L1"
      },
    ...
  ]
}

This endpoint retrieves team standings.

HTTP Request

GET https://api.balldontlie.io/nhl/v1/standings

Query Parameters

Parameter Required Description
season false Filter by season
conference false Filter by conference name
division false Filter by division name

Box Scores

Get Box Scores

curl "https://api.balldontlie.io/nhl/v1/box_scores?game_ids[]=74509" \
  -H "Authorization: YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "data": [
    {
        "player": {
            "id": 22,
            "first_name": "Jordan",
            "last_name": "Staal",
            "full_name": "Jordan Staal",
            "position_code": "C",
            "shoots_catches": "L",
            "height_in_inches": 76,
            "weight_in_pounds": 220,
            "birth_date": "1988-09-09",
            "birth_place": "Thunder Bay, ON, CAN",
        },
        "team": {
            "id": 18,
            "full_name": "Carolina Hurricanes",
            "tricode": "CAR",
            "conference_name": "Eastern",
            "division_name": "Metropolitan"
        },
        "game": {
            "id": 74509,
            "season": 2024,
            "game_date": "2025-05-20",
            "start_time_utc": "2025-05-21T00:00:00.000Z",
            "home_team": {
                "id": 18,
                "full_name": "Carolina Hurricanes",
                "tricode": "CAR",
                "conference_name": "Eastern",
                "division_name": "Metropolitan"
            },
            "away_team": {
                "id": 17,
                "full_name": "Florida Panthers",
                "tricode": "FLA",
                "conference_name": "Eastern",
                "division_name": "Atlantic"
            },
            "home_sog": 10,
            "away_sog": 7,
            "home_score": 1,
            "away_score": 2,
            "venue": "Lenovo Center",
            "game_state": "LIVE",
            "period": 1,
            "time_remaining": "06:30",
            "postseason": true
        },
        "position": "C",
        "goals": 0,
        "assists": 0,
        "points": 0,
        "plus_minus": -1,
        "penalty_minutes": 0,
        "power_play_goals": 0,
        "shots_on_goal": 0,
        "faceoff_winning_pctg": 0.625,
        "time_on_ice": "06:03",
        "blocked_shots": 0,
        "hits": 2,
        "shifts": 9,
        "giveaways": 0,
        "takeaways": 0,
        "sweater_number": 11
    },
      ...
  ],
  "meta": {
    "next_cursor": null,
    "per_page": 25
  }
}

This endpoint retrieves box scores for games.

HTTP Request

GET https://api.balldontlie.io/nhl/v1/box_scores

Query Parameters

Parameter Required Description
cursor false The cursor for pagination
per_page false Number of results per page (max 100)
season false Filter by season
game_ids false Filter by specific game IDs
team_ids false Filter by team IDs
player_ids false Filter by player IDs
dates false Filter by specific dates (YYYY-MM-DD)
shell