nhl-api-py

The library is organized into functional modules that map to NHL API endpoints:

• teams: Team information, rosters, and franchise IDs.
• schedule: Game schedules (daily, weekly, team-specific, playoffs).
• stats: Player and team statistics (basic, summary, and advanced via Query Builder).
• edge: EDGE-related data (shot speed, skate speed, etc.).
• standings: Current and historical league standings.
• game_center: Box scores, play-by-play, and game summaries.
• players: Players by team and prospects.
• misc: Glossary, configuration, and country info.
• helpers: Experimental utilities for complex tasks (e.g., getting game IDs by season). Note: Helpers may perform many requests and include built-in sleeping to avoid rate limits; you can override this with sleep=False.

The edge module provides access to NHL EDGE puck and player tracking data, including shot speed, skating speed, distance skated, zone time, and shot location analytics for skaters, goalies, and teams.

Note: EDGE data is only available from the 2021-2022 season onward. Access the module via client.edge on an NHLClient instance.

from nhlpy import NHLClient

client = NHLClient()
# Access the edge module
edge_module = client.edge

NHL Game IDs follow a specific structured format: YYYYTTNNNN.

• YYYY: The season start year.
• TT: The game type code:
  • 01: Preseason
  • 02: Regular Season
  • 03: Playoffs
• NNNN: The sequential game number.

Example: 2023020280 represents the 280th regular season game of the 2023 season.

The helpers module provides convenience methods that aggregate data from multiple NHL API calls into single results. You can access it via client.helpers on an NHLClient instance.

Performance Warning: Every method in this module makes multiple API calls internally (typically 32, one per NHL team) with built-in sleep delays between requests to avoid rate limiting. These methods are significantly slower than individual API calls. Expect execution times of 30 seconds to several minutes depending on the method and sleep rate.

When building a query, the QueryContext object tracks whether the provided filters are valid. If a filter is invalid (due to bad data or wrong options), it will be excluded from the final query, but the rest of the valid filters will still be processed.

You can check for errors using:

• query_context.is_valid(): Returns False if any filters failed validation.
• query_context.errors: Contains the error details encountered during the build process.

... 
query_context: QueryContext = query_builder.build(filters=filters)
if not query_context.is_valid():
    print(f"Errors encountered: {query_context.errors}")

The misc module provides utility and reference data endpoints for the NHL API. You can access it via the client.misc attribute on an NHLClient instance. It is used for retrieving glossary definitions, stats configuration, country lists, historical season rules, and draft information.

from nhlpy import NHLClient

client = NHLClient()
# Access the misc module
misc_module = client.misc

The Stats module provides access to player statistics, team statistics, goalie statistics, and advanced query-based stat lookups. You can access this module through the .stats attribute on an instance of NHLClient.

from nhlpy import NHLClient

client = NHLClient()
# Access stats via client.stats
stats_module = client.stats

You can install the package using pip or uv.

pip install nhl-api-py
# - OR -
uv add nhl-api-py

To use the library, instantiate the NHLClient and access its sub-modules (like teams, standings, or schedule) to retrieve NHL data.

from nhlpy import NHLClient

# Basic usage
client = NHLClient()

# Get all teams
teams = client.teams.teams()

# Get current standings
standings = client.standings.league_standings()

# Get today's games
games = client.schedule.daily_schedule()

When initializing NHLClient, you can pass several configuration options to control behavior such as logging, timeouts, and SSL verification.

from nhlpy import NHLClient

# All available configurations
client = NHLClient(
    debug=True,           # Enable debug logging
    timeout=30,           # Request timeout in seconds
    ssl_verify=True,      # SSL certificate verification
    follow_redirects=True # Follow HTTP redirects
)