Skip to content

Commit ab8b345

Browse files
coreyjscoreyjs
committed
#111 README updates for Edge endpoints. general cleanup
1 parent 115c170 commit ab8b345

File tree

1 file changed

+77
-87
lines changed

1 file changed

+77
-87
lines changed

‎README.md‎

Lines changed: 77 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ If you find any, open a ticket or post in the discussions tab. I would love to
4343

4444
```bash
4545
pip install nhl-api-py
46+
# - OR -
47+
uv add nhl-api-py
4648
```
4749

4850
```python
@@ -90,6 +92,8 @@ More in depth examples can be found in the wiki, feel free to add more: [Example
9092

9193
Im available on [Bluesky](https://bsky.app/profile/coreyjs.dev) or the [twit](https://x.com/corey_builds) for any questions or just general chats about enhancements.
9294

95+
---
96+
9397
## API Modules
9498

9599
This project is organized into several sub modules, each representing a different endpoint of the NHL API.
@@ -102,12 +106,15 @@ They are grouped by function to make the library easier to navigate and use. Th
102106
- **`standings`**: Contains endpoints related to NHL standings, including current standings and historical standings.
103107
- **`game_center`**: Contains endpoints related to game center data, including box scores, play-by-play data, and game summaries.
104108
- **`misc`**: Contains miscellaneous endpoints that don't fit into the other categories, such as glossary terms, configuration data, and country information.
105-
109+
- **`players`**: Get Players by team and prospects.
106110
### Helpers Module
107111
- **`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.
108112

109113

110114
Do you have a specific use case or cool code snippet you use over and over? If its helpful to others please open a PR and add a helper.
115+
116+
---
117+
111118
# Teams
112119

113120
Get information about NHL teams, rosters, and franchises.
@@ -156,7 +163,7 @@ print(f"Forwards: {len(roster['forwards'])}")
156163
print(f"Defensemen: {len(roster['defensemen'])}")
157164
print(f"Goalies: {len(roster['goalies'])}")
158165
```
159-
166+
---
160167

161168
# Schedule
162169

@@ -301,7 +308,7 @@ CHI @ UTA - 2024-10-09T02:00:00Z
301308
```
302309
</details>
303310

304-
311+
---
305312

306313
# Stats
307314

@@ -391,134 +398,117 @@ for i, player in enumerate(stats[:5]):
391398
4. David Pastrnak: 106 points
392399
5. Mitch Marner: 102 points
393400
```
401+
---
394402

395403
# Edge
396404

397-
Get EDGE related player and team data. (Note, these endpoints were well hidden and behave
398-
a bit differently. Their payloads are less verbose than the others.)
405+
Access NHL EDGE statistics - advanced player and puck tracking data including shot speed, skating speed,
406+
distance traveled, and zone time metrics. This data provides insights beyond traditional statistics.
407+
408+
## What are EDGE Stats?
399409

400-
It should be noted that these endpoints may be unstable and change often resulting in
401-
failed requests. These seem to be for internal use for the NHL edge graphics, so data is often structured strangely.
410+
EDGE stats capture real-time tracking data from NHL games:
411+
- **Skater Data**: Shot velocity, skating speed, burst counts, distance covered, zone time
412+
- **Goalie Data**: Save locations, shot tracking, 5v5 performance breakdowns
413+
- **Team Data**: Aggregate team skating metrics, shot patterns, and zone possession
414+
415+
Use EDGE endpoints when you need physical performance metrics. Use the [Stats](#stats) endpoints
416+
for traditional statistics like goals, assists, and points.
417+
418+
## Usage Patterns
419+
420+
All EDGE methods support two patterns:
421+
- **Current season**: Omit the `season` parameter or pass `None` to get current data
422+
- **Specific season**: Pass season as 8-digit string (e.g., `"20232024"`)
423+
424+
The `game_type` parameter defaults to `2` (regular season) but can be set to `3` for playoffs.
425+
426+
## Important Notes
427+
428+
These endpoints may be unstable and change frequently. They appear to be designed for internal
429+
NHL use for broadcast graphics. Response structures can vary and data availability may be inconsistent.
430+
431+
## Skater Metrics
402432

403433
```python
434+
# Get comprehensive EDGE statistics for a skater
404435
client.edge.skater_detail(player_id='8478402', season='20252026')
405436

437+
# Get shot speed analytics (max speed, average speed)
406438
client.edge.skater_shot_speed_detail(player_id='8478402', season='20252026')
407439

440+
# Get skating speed metrics (burst counts, max speed)
408441
client.edge.skater_skating_speed_detail(player_id='8478402', season='20252026')
409442

443+
# Get shot location patterns and heat maps
410444
client.edge.skater_shot_location_detail(player_id='8478402', season='20252026')
411445

446+
# Get distance traveled per game and per shift
412447
client.edge.skater_skating_distance_detail(player_id='8478402', season='20252026')
413448

449+
# Get comparison data vs league averages
414450
client.edge.skater_comparison(player_id='8478402', season='20252026')
415451

452+
# Get time spent in each zone (offensive/defensive/neutral)
416453
client.edge.skater_zone_time(player_id='8478402', season='20252026')
417454

455+
# Get league-wide skater EDGE statistics overview
418456
client.edge.skater_landing(season='20252026')
419457

458+
# Get CAT (Catch All Tracking) EDGE statistics
420459
client.edge.cat_skater_detail(player_id='8478402', season='20252026')
460+
```
461+
462+
## Goalie Metrics
421463

422-
client.edge.goalie_detail(player_id='8478402', season='20252026')
464+
```python
465+
# Get comprehensive EDGE statistics for a goalie
466+
client.edge.goalie_detail(player_id='8476945', season='20252026')
423467

424-
client.edge.goalie_shot_location_detail(player_id='8478402', season='20252026')
468+
# Get shot location data and save percentages by zone
469+
client.edge.goalie_shot_location_detail(player_id='8476945', season='20252026')
425470

426-
client.edge.goalie_5v5_detail(player_id='8478402', season='20252026')
471+
# Get 5-on-5 performance statistics
472+
client.edge.goalie_5v5_detail(player_id='8476945', season='20252026')
427473

428-
client.edge.goalie_comparison(player_id='8478402', season='20252026')
474+
# Get comparison data vs league averages
475+
client.edge.goalie_comparison(player_id='8476945', season='20252026')
429476

430-
client.edge.goalie_save_percentage_detail(player_id='8478402', season='20252026')
477+
# Get detailed save percentage breakdowns by situation
478+
client.edge.goalie_save_percentage_detail(player_id='8476945', season='20252026')
431479

480+
# Get league-wide goalie EDGE statistics overview
432481
client.edge.goalie_landing(season='20252026')
433482

434-
client.edge.cat_goalie_detail(player_id='8478402', season='20252026')
483+
# Get CAT (Catch All Tracking) EDGE statistics
484+
client.edge.cat_goalie_detail(player_id='8476945', season='20252026')
485+
```
486+
487+
## Team Metrics
435488

489+
```python
490+
# Get comprehensive EDGE statistics for a team
436491
client.edge.team_detail(team_id='19', season='20252026')
437492

493+
# Get team skating distance statistics
438494
client.edge.team_skating_distance_detail(team_id='19', season='20252026')
439495

496+
# Get team zone time breakdowns
440497
client.edge.team_zone_time_details(team_id='19', season='20252026')
441498

499+
# Get team shot location patterns
442500
client.edge.team_shot_location_detail(team_id='19', season='20252026')
443501

444-
client.edge.team_landing(team_id='19', season='20252026')
445-
502+
# Get team shot speed analytics
446503
client.edge.team_shot_speed_detail(team_id='19', season='20252026')
447504

505+
# Get team skating speed metrics
448506
client.edge.team_skating_speed_detail(team_id='19', season='20252026')
449-
```
450-
451-
## Skater Detail
452-
453-
```python
454-
detail = client.edge.skater_detail(player_id='8478402', season="20252026")
455507

456-
...
457-
'skatingSpeed': {
458-
'burstsOver20': {
459-
'leagueAvg': {
460-
'value': 13.9179
461-
},
462-
'percentile': 1.0,
463-
'value': 91
464-
},
465-
'speedMax': {
466-
'imperial': 24.612,
467-
'leagueAvg': {
468-
'imperial': 21.7285,
469-
'metric': 34.9685
470-
},
471-
'metric': 39.609,
472-
'overlay': {
473-
'awayTeam': {
474-
'abbrev': 'CGY',
475-
'score': 4
476-
},
477-
'gameDate': '2025-10-08',
478-
'gameOutcome': {
479-
'lastPeriodType': 'SO'
480-
},
481-
'gameType': 2,
482-
'homeTeam': {
483-
'abbrev': 'EDM',
484-
'score': 3
485-
},
486-
'periodDescriptor': {
487-
'maxRegulationPeriods': 3,
488-
'number': 2,
489-
'periodType': 'REG'
490-
},
491-
'player': {
492-
'firstName': {
493-
'default': 'Connor'
494-
},
495-
'lastName': {
496-
'default': 'McDavid'
497-
}
498-
},
499-
'timeInPeriod': '08:04'
500-
},
501-
'percentile': 1.0
502-
...
508+
# Get league-wide team EDGE statistics overview
509+
client.edge.team_landing(season='20252026')
503510
```
504511

505-
[Example Response](https://github.com/coreyjs/nhl-api-py/wiki/edge.skater_detail)
506-
507-
508-
## Skater Shot Speed Details
509-
510-
```python
511-
detail = client.edge.skater_shot_speed_detail(player_id='8478402', season="20252026")
512-
```
513-
514-
[Example Response](https://github.com/coreyjs/nhl-api-py/wiki/edge.skater_shot_speed_detail)
515-
516-
517-
## Skater Skating Speed Detail
518-
519-
```python
520-
detail = client.edge.skater_skating_speed_detail(player_id='8478402', season='20252026')
521-
```
522512

523513
---
524514

@@ -569,7 +559,7 @@ for team in standings['standings']:
569559
for division, team in divisions.items():
570560
print(f"{division}: {team['teamName']['default']} ({team['points']} pts)")
571561
```
572-
562+
---
573563

574564
# Game Center
575565

@@ -645,7 +635,7 @@ for play in play_by_play.get('plays', []):
645635
for period, shots in shots_by_period.items():
646636
print(f"Period {period}: {shots} shots")
647637
```
648-
638+
---
649639

650640
# Misc
651641

0 commit comments

Comments
 (0)