nhl-api-py 3.2.3__tar.gz → 3.4.0__tar.gz

{nhl_api_py-3.2.3 → nhl_api_py-3.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: nhl-api-py
-Version: 3.2.3
+Version: 3.4.0
 Summary: NHL API (Updated for 2025/2026) and EDGE Stats.  For standings, team stats, outcomes, player information.  Contains each individual API endpoint as well as convience methods as well as pythonic query builder for more indepth EDGE stats.
 Home-page: https://github.com/coreyjs/nhl-api-py
 License: Apache-2.0
@@ -43,6 +43,7 @@ Description-Content-Type: text/markdown
   - [Standings](#standings)
   - [Game Center](#game-center)
   - [Misc](#misc)
+  - [Records](#records)
 - [Advanced Usage](#advanced-usage)
   - [Query Builder](#stats-with-querybuilder)
 - [Examples & Wiki](#examples--wiki)
@@ -59,6 +60,12 @@ Note: I created this to help me with some machine learning
 projects around the NHL and the NHL data sets.  Special thanks to https://github.com/erunion/sport-api-specifications/tree/master/nhl,
 https://gitlab.com/dword4/nhlapi/-/blob/master/stats-api.md and https://github.com/Zmalski/NHL-API-Reference.
 
+### AI Note:
+
+This library was written by hand before the advent of agentic coding.  Going forward this repo will continue to be 
+developed with an engineer first approach.  Any agentic tools will be used for architectural reviews or general code reviews.  
+AI heavy PRs will not be accepted, but we are open to any discussion that makes this library better for the user.
+
 ### Developer Note: This is being updated with the new, also undocumented, NHL API.  
 
 This started as a project around the old NHL API, that got deprecated in 2023(?). This project has evolved 
@@ -135,6 +142,7 @@ They are grouped by function to make the library easier to navigate and use.  Th
 - **`game_center`**: Contains endpoints related to game center data, including box scores, play-by-play data, and game summaries.
 - **`misc`**: Contains miscellaneous endpoints that don't fit into the other categories, such as glossary terms, configuration data, and country information.
 - **`players`**: Get Players by team and prospects.
+- **`records`**: Historical data from the NHL Records API: franchise history, the full draft history, attendance, venues, and hundreds of record lists (streaks, fastest goals, etc.).
 ### Helpers Module
 - **`helpers`**: Contains helper functions and utilities for working with the NHL API, such as getting game IDs by season or calculating player statistics. These are experimental and often times make many requests, can return DataFrames or do calculations. Stuff I find myself doing over and over I tend to move into helpers for convenience. They are often cross domain, involve many sub requests, may integrate more machine learning techniques, or just make it easier to get the data you want. These will have built in sleeping to avoid hitting the API too hard, but you can override this by setting the `sleep` parameter to `False` in the function call.
 
@@ -717,6 +725,32 @@ for term in stat_terms:
             continue
 ```
 
+---
+
+# Records
+
+Historical data from the NHL Records API (`records.nhl.com`). Curated methods return a list of rows; `query()` reaches any of the ~445 records endpoints by name. See [docs/records.md](docs/records.md) for every method and the full endpoint catalog.
+
+```python
+# Franchise history
+franchises = client.records.franchises()
+sabres = client.records.franchise_detail(team_id=7)
+totals = client.records.franchise_totals(game_type_id=2, sort="wins")
+seasons = client.records.franchise_season_results(franchise_id=19, game_type_id=2)
+
+# Draft history (back to 1963)
+first_round = client.records.draft(draft_year=2024, round_number=1, sort=[("overallPickNumber", "ASC")])
+sabres_picks = client.records.draft_by_team(team_id=7)
+
+# Any records endpoint, with Cayenne filters, sorting and pagination
+top_scorers = client.records.query(
+    "skater-career-scoring-regular-season", cayenne_exp="franchiseId=19", sort="points", limit=10
+)
+streaks = client.records.query("goalie-shutout-streak", limit=10)
+```
+
+Note: without a `limit`, records endpoints return every row, which can be large (e.g. the full draft is ~8 MB).
+
 ---
 # Advanced Usage
 

{nhl_api_py-3.2.3 → nhl_api_py-3.4.0}/README.md

@@ -15,6 +15,7 @@
   - [Standings](#standings)
   - [Game Center](#game-center)
   - [Misc](#misc)
+  - [Records](#records)
 - [Advanced Usage](#advanced-usage)
   - [Query Builder](#stats-with-querybuilder)
 - [Examples & Wiki](#examples--wiki)
@@ -31,6 +32,12 @@ Note: I created this to help me with some machine learning
 projects around the NHL and the NHL data sets.  Special thanks to https://github.com/erunion/sport-api-specifications/tree/master/nhl,
 https://gitlab.com/dword4/nhlapi/-/blob/master/stats-api.md and https://github.com/Zmalski/NHL-API-Reference.
 
+### AI Note:
+
+This library was written by hand before the advent of agentic coding.  Going forward this repo will continue to be 
+developed with an engineer first approach.  Any agentic tools will be used for architectural reviews or general code reviews.  
+AI heavy PRs will not be accepted, but we are open to any discussion that makes this library better for the user.
+
 ### Developer Note: This is being updated with the new, also undocumented, NHL API.  
 
 This started as a project around the old NHL API, that got deprecated in 2023(?). This project has evolved 
@@ -107,6 +114,7 @@ They are grouped by function to make the library easier to navigate and use.  Th
 - **`game_center`**: Contains endpoints related to game center data, including box scores, play-by-play data, and game summaries.
 - **`misc`**: Contains miscellaneous endpoints that don't fit into the other categories, such as glossary terms, configuration data, and country information.
 - **`players`**: Get Players by team and prospects.
+- **`records`**: Historical data from the NHL Records API: franchise history, the full draft history, attendance, venues, and hundreds of record lists (streaks, fastest goals, etc.).
 ### Helpers Module
 - **`helpers`**: Contains helper functions and utilities for working with the NHL API, such as getting game IDs by season or calculating player statistics. These are experimental and often times make many requests, can return DataFrames or do calculations. Stuff I find myself doing over and over I tend to move into helpers for convenience. They are often cross domain, involve many sub requests, may integrate more machine learning techniques, or just make it easier to get the data you want. These will have built in sleeping to avoid hitting the API too hard, but you can override this by setting the `sleep` parameter to `False` in the function call.
 
@@ -689,6 +697,32 @@ for term in stat_terms:
             continue
 ```
 
+---
+
+# Records
+
+Historical data from the NHL Records API (`records.nhl.com`). Curated methods return a list of rows; `query()` reaches any of the ~445 records endpoints by name. See [docs/records.md](docs/records.md) for every method and the full endpoint catalog.
+
+```python
+# Franchise history
+franchises = client.records.franchises()
+sabres = client.records.franchise_detail(team_id=7)
+totals = client.records.franchise_totals(game_type_id=2, sort="wins")
+seasons = client.records.franchise_season_results(franchise_id=19, game_type_id=2)
+
+# Draft history (back to 1963)
+first_round = client.records.draft(draft_year=2024, round_number=1, sort=[("overallPickNumber", "ASC")])
+sabres_picks = client.records.draft_by_team(team_id=7)
+
+# Any records endpoint, with Cayenne filters, sorting and pagination
+top_scorers = client.records.query(
+    "skater-career-scoring-regular-season", cayenne_exp="franchiseId=19", sort="points", limit=10
+)
+streaks = client.records.query("goalie-shutout-streak", limit=10)
+```
+
+Note: without a `limit`, records endpoints return every row, which can be large (e.g. the full draft is ~8 MB).
+
 ---
 # Advanced Usage
 

{nhl_api_py-3.2.3 → nhl_api_py-3.4.0}/nhlpy/api/edge.py

@@ -27,6 +27,19 @@ class Edge:
         Returns:
             dict: Dictionary containing detailed EDGE statistics for the skater
 
+        Key Response Fields:
+            player.firstName.default (str): Player first name
+            player.lastName.default (str): Player last name
+            player.goals (int): Total goals scored
+            player.points (int): Total points
+            topShotSpeed.imperial (float): Top shot speed in mph
+            skatingSpeed.speedMax.imperial (float): Maximum skating speed in mph
+            totalDistanceSkated.imperial (float): Total distance skated in miles
+            zoneTimeDetails.offensiveZonePctg (float): Offensive zone time percentage
+
+        Response Docs:
+            docs/edge.md
+
         Example:
             client.edge.skater_detail(player_id=8478402)
             client.edge.skater_detail(player_id=8478402, season=20232024, game_type=2)
@@ -47,6 +60,14 @@ class Edge:
 
         Returns:
             dict: Shot speed statistics including maximum and average speeds
+
+        Key Response Fields:
+            shotSpeedData (list): Shot speed entries with percentiles
+            topShotSpeed.imperial (float): Top shot speed in mph
+            averageShotSpeed.imperial (float): Average shot speed in mph
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-shot-speed-detail/{player_id}/now"
@@ -64,6 +85,14 @@ class Edge:
 
         Returns:
             dict: Skating speed statistics including burst speed and average speed
+
+        Key Response Fields:
+            skatingSpeedData (list): Skating speed entries with burst counts
+            speedMax.imperial (float): Maximum skating speed in mph
+            burstCount (int): Number of speed bursts
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-skating-speed-detail/{player_id}/now"
@@ -81,6 +110,14 @@ class Edge:
 
         Returns:
             dict: Shot location data including shooting patterns and heat maps
+
+        Key Response Fields:
+            shotLocations (list): Shot data grouped by area
+            area (str): Ice zone identifier
+            shotCount (int): Number of shots from each area
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-shot-location-detail/{player_id}/now"
@@ -98,6 +135,14 @@ class Edge:
 
         Returns:
             dict: Distance traveled statistics per game and per shift
+
+        Key Response Fields:
+            distanceData (list): Distance entries per game
+            totalDistance.imperial (float): Total distance skated in miles
+            gameMax.imperial (float): Maximum distance skated in a single game in miles
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-skating-distance-detail/{player_id}/now"
@@ -115,6 +160,14 @@ class Edge:
 
         Returns:
             dict: Comparison data relative to league averages
+
+        Key Response Fields:
+            comparisonData (list): Comparison metrics vs league
+            leagueAverage (float): League average value for each metric
+            playerValue (float): Player value for each metric
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-comparison/{player_id}/now"
@@ -132,6 +185,14 @@ class Edge:
 
         Returns:
             dict: Time spent in offensive, defensive, and neutral zones
+
+        Key Response Fields:
+            offensiveZonePctg (float): Offensive zone time percentage
+            defensiveZonePctg (float): Defensive zone time percentage
+            neutralZonePctg (float): Neutral zone time percentage
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/skater-zone-time/{player_id}/now"
@@ -150,6 +211,14 @@ class Edge:
 
         Returns:
             dict: Overview of league-wide skater EDGE statistics
+
+        Key Response Fields:
+            leaders.hardestShot (list): League leaders for hardest shot
+            leaders.maxSkatingSpeed (list): League leaders for max skating speed
+            leaders.totalDistanceSkated (list): League leaders for total distance skated
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = "edge/skater-landing/now"
@@ -167,6 +236,14 @@ class Edge:
 
         Returns:
             dict: CAT EDGE statistics for the skater
+
+        Key Response Fields:
+            player (dict): Compact player summary with EDGE highlights
+            shotSpeed (dict): Condensed shot speed data
+            skatingSpeed (dict): Condensed skating speed data
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"cat/edge/skater-detail/{player_id}/now"
@@ -194,6 +271,16 @@ class Edge:
         Returns:
             dict: Dictionary containing detailed EDGE statistics for the goalie
 
+        Key Response Fields:
+            player.wins (int): Total wins
+            player.savePctg (float): Overall save percentage
+            stats.goalsAgainstAvg.value (float): Goals against average
+            stats.gamesAbove900.value (float): Games with save pct above .900
+            shotLocationSummary (list): Save data grouped by shot area
+
+        Response Docs:
+            docs/edge.md
+
         Example:
             client.edge.goalie_detail(player_id=8476945)
             client.edge.goalie_detail(player_id=8476945, season=20232024, game_type=2)
@@ -214,6 +301,14 @@ class Edge:
 
         Returns:
             dict: Shot location data faced by the goalie including save percentages by zone
+
+        Key Response Fields:
+            shotLocations (list): Save data grouped by shot location
+            area (str): Ice zone identifier
+            savePctg (float): Save percentage for each area
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/goalie-shot-location-detail/{player_id}/now"
@@ -231,6 +326,14 @@ class Edge:
 
         Returns:
             dict: 5-on-5 performance statistics and save percentages
+
+        Key Response Fields:
+            fiveOnFiveStats (dict): 5-on-5 performance metrics
+            savePctg5v5 (float): Save percentage at 5-on-5
+            goalsAgainstAvg5v5 (float): Goals against average at 5-on-5
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/goalie-5v5-detail/{player_id}/now"
@@ -248,6 +351,14 @@ class Edge:
 
         Returns:
             dict: Comparison data relative to league averages
+
+        Key Response Fields:
+            comparisonData (list): Comparison metrics vs league
+            leagueAverage (float): League average value for each metric
+            playerValue (float): Player value for each metric
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/goalie-comparison/{player_id}/now"
@@ -265,6 +376,14 @@ class Edge:
 
         Returns:
             dict: Detailed save percentage breakdowns by situation and location
+
+        Key Response Fields:
+            savePctgBreakdown (list): Save percentage by situation type
+            overallSavePctg (float): Overall save percentage
+            highDangerSavePctg (float): Save percentage on high-danger chances
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/goalie-save-percentage-detail/{player_id}/now"
@@ -283,6 +402,14 @@ class Edge:
 
         Returns:
             dict: Overview of league-wide goalie EDGE statistics
+
+        Key Response Fields:
+            leaders (dict): League leaders for goalie EDGE stats
+            topSavePctg (list): Leaders by save percentage
+            topGamesAbove900 (list): Leaders by games above .900
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = "edge/goalie-landing/now"
@@ -300,6 +427,14 @@ class Edge:
 
         Returns:
             dict: CAT EDGE statistics for the goalie
+
+        Key Response Fields:
+            player (dict): Compact goalie summary with EDGE highlights
+            savePctg (float): Condensed save percentage data
+            goalsAgainstAvg (float): Condensed goals against average
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"cat/edge/goalie-detail/{player_id}/now"
@@ -327,6 +462,18 @@ class Edge:
         Returns:
             dict: Dictionary containing detailed EDGE statistics for the team
 
+        Key Response Fields:
+            team.abbrev (str): Team abbreviation
+            team.wins (int): Total wins
+            team.points (int): Total points
+            shotSpeed.topShotSpeed.imperial (float): Top shot speed in mph
+            skatingSpeed.speedMax.imperial (float): Maximum skating speed in mph
+            distanceSkated.total.imperial (float): Total distance skated in miles
+            zoneTimeDetails.offensiveZonePctg (float): Offensive zone time percentage
+
+        Response Docs:
+            docs/edge.md
+
         Example:
             client.edge.team_detail(team_id=10)
             client.edge.team_detail(team_id=10, season=20232024, game_type=2)
@@ -347,6 +494,14 @@ class Edge:
 
         Returns:
             dict: Team skating distance statistics per game and per player
+
+        Key Response Fields:
+            distanceData (list): Distance entries per game and per player
+            totalDistance.imperial (float): Total team distance skated in miles
+            perGameAvg.imperial (float): Average distance per game in miles
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/team-skating-distance-detail/{team_id}/now"
@@ -364,6 +519,14 @@ class Edge:
 
         Returns:
             dict: Team time spent in offensive, defensive, and neutral zones
+
+        Key Response Fields:
+            offensiveZonePctg (float): Offensive zone time percentage
+            defensiveZonePctg (float): Defensive zone time percentage
+            neutralZonePctg (float): Neutral zone time percentage
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/team-zone-time-details/{team_id}/now"
@@ -381,6 +544,14 @@ class Edge:
 
         Returns:
             dict: Team shot location data including shooting patterns and heat maps
+
+        Key Response Fields:
+            shotLocations (list): Shot data grouped by area
+            area (str): Ice zone identifier
+            shotCount (int): Number of shots from each area
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/team-shot-location-detail/{team_id}/now"
@@ -399,6 +570,14 @@ class Edge:
 
         Returns:
             dict: Overview of league-wide team EDGE statistics
+
+        Key Response Fields:
+            leaders (dict): Team EDGE leaders across categories
+            topShotSpeed (list): Leaders by team shot speed
+            topSkatingSpeed (list): Leaders by team skating speed
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = "edge/team-landing/now"
@@ -416,6 +595,14 @@ class Edge:
 
         Returns:
             dict: Team shot speed statistics including maximum and average speeds
+
+        Key Response Fields:
+            shotSpeedData (list): Shot speed entries by player
+            topShotSpeed.imperial (float): Top team shot speed in mph
+            averageShotSpeed.imperial (float): Average team shot speed in mph
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/team-shot-speed-detail/{team_id}/now"
@@ -433,6 +620,14 @@ class Edge:
 
         Returns:
             dict: Team skating speed statistics including burst speed and average speed
+
+        Key Response Fields:
+            skatingSpeedData (list): Skating speed entries by player
+            speedMax.imperial (float): Maximum team skating speed in mph
+            averageSpeed.imperial (float): Average team skating speed in mph
+
+        Response Docs:
+            docs/edge.md
         """
         if season is None:
             resource = f"edge/team-skating-speed-detail/{team_id}/now"