Metadata-Version: 2.4
Name: nhl-stats-api-client
Version: 1.0.2
Summary: A comprehensive Python client for accessing NHL statistics and data
Home-page: https://github.com/liahimratman/nhl-api-client
Author: Mikhail Korotkov
Author-email: Mikhail Korotkov <ma.korotkov.eu@gmail.com>
Maintainer-email: Mikhail Korotkov <ma.korotkov.eu@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/liahimratman/nhl-api-client
Project-URL: Documentation, https://github.com/liahimratman/nhl-api-client#readme
Project-URL: Repository, https://github.com/liahimratman/nhl-api-client
Project-URL: Bug Reports, https://github.com/liahimratman/nhl-api-client/issues
Keywords: nhl,hockey,api,statistics,sports,analytics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: pandas>=1.3.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# NHL API Client

A comprehensive Python client for accessing NHL statistics and data through various official NHL APIs. This library provides easy access to player stats, team information, schedules, standings, and more.

## Features

- 🏒 **Player Statistics**: Access comprehensive player stats including scoring, real-time, power play, penalty kill, and faceoff data
- 🥅 **Goalie Statistics**: Retrieve goalie stats, advanced metrics, and shootout performance
- 🏆 **Team Data**: Get team statistics, power play/penalty kill data, and faceoff percentages
- 📅 **Schedule & Standings**: Access current schedules, standings, and game information
- 🎯 **Advanced Analytics**: Built-in support for advanced statistical analysis
- 📊 **Data Export**: Export data to CSV, JSON, and Excel formats
- 🚀 **Easy to Use**: Simple, intuitive API with comprehensive error handling

## Installation

### From PyPI (when published)

```bash
pip install nhl-api-client
```

### From Source

```bash
git clone https://github.com/yourusername/nhl-api-client.git
cd nhl-api-client
pip install -e .
```

### Requirements

- Python 3.7+
- pandas
- requests
- openpyxl (for Excel export)

## Quick Start

```python
from nhl_api_client import NHLAPIClient

# Initialize the client
client = NHLAPIClient()

# Get player stats for Connor McDavid (2023-24 season)
player_stats = client.get_player_season_stats(8478402, "20232024")
print(f"Goals: {player_stats['goals']}, Assists: {player_stats['assists']}")

# Get current standings
standings = client.get_standings_now()

# Get today's schedule
schedule = client.get_schedule_now()

# Export top scorers to CSV
top_scorers = client.get_top_scorers("20232024", limit=50)
top_scorers.to_csv("top_scorers.csv", index=False)
```

## API Reference

### Player Statistics

#### Individual Player Methods

```python
# Get basic season stats for a player
stats = client.get_player_season_stats(player_id, season_id)

# Get real-time stats (hits, blocks, giveaways, etc.)
realtime = client.get_player_realtime_stats(player_id, season_id)

# Get biographical information
bio = client.get_player_bios(player_id)

# Get power play statistics
pp_stats = client.get_player_powerplay_stats(player_id, season_id)

# Get penalty statistics
penalty_stats = client.get_player_penalty_stats(player_id, season_id)

# Get faceoff statistics
faceoff_stats = client.get_player_faceoff_stats(player_id, season_id)

# Get comprehensive stats from multiple endpoints
all_stats = client.get_comprehensive_player_stats(player_id, season_id)
```

#### Bulk Player Data Methods

```python
# Get top scorers
top_scorers = client.get_top_scorers(season_id, limit=100)

# Get skater stats by category
summary_stats = client.get_skater_stats_by_season(season_id, limit=500)
realtime_stats = client.get_skater_realtime_stats(season_id, limit=500)
powerplay_stats = client.get_skater_powerplay_stats(season_id, limit=500)
penaltykill_stats = client.get_skater_penaltykill_stats(season_id, limit=500)
penalty_stats = client.get_skater_penalty_stats(season_id, limit=500)
faceoff_stats = client.get_skater_faceoff_stats(season_id, limit=500)
shootout_stats = client.get_skater_shootout_stats(season_id, limit=500)
timeonice_stats = client.get_skater_timeonice_stats(season_id, limit=500)
```

### Goalie Statistics

```python
# Get goalie summary stats
goalie_stats = client.get_goalie_stats(season_id, limit=100)

# Get advanced goalie stats
advanced_stats = client.get_goalie_advanced_stats(season_id, limit=100)

# Get goalie biographical information
goalie_bios = client.get_goalie_bios(season_id, limit=100)

# Get shootout statistics
shootout_stats = client.get_goalie_shootout_stats(season_id, limit=100)

# Get starts and wins data
starts_stats = client.get_goalie_starts_stats(season_id, limit=100)
```

### Team Statistics

```python
# Get team summary statistics
team_stats = client.get_team_stats(season_id)

# Get team power play stats
pp_stats = client.get_team_powerplay_stats(season_id)

# Get team penalty kill stats
pk_stats = client.get_team_penaltykill_stats(season_id)

# Get team faceoff percentages
faceoff_stats = client.get_team_faceoff_percentages(season_id)

# Get team real-time stats
realtime_stats = client.get_team_realtime_stats(season_id)

# Get penalty statistics
penalty_stats = client.get_team_penalty_stats(season_id)
```

### Schedule and Standings

```python
# Get current standings
standings = client.get_standings_now()

# Get today's schedule
today_schedule = client.get_schedule_now()

# Get schedule for a specific date
date_schedule = client.get_schedule_by_date("2024-01-15")

# Get team's full season schedule
team_schedule = client.get_club_schedule("TOR")  # Toronto Maple Leafs

# Get team roster
roster = client.get_team_roster("TOR")
```

### Game Data

```python
# Get game center data
game_data = client.get_gamecenter(game_id)

# Get play-by-play data
pbp_data = client.get_play_by_play(game_id)

# Get player game logs
game_log = client.get_player_game_log(player_id, season_id)
```

## Usage Examples

### Example 1: Player Analysis

```python
from nhl_api_client import NHLAPIClient

client = NHLAPIClient()

# Analyze Connor McDavid's 2023-24 season
mcdavid_id = 8478402
season = "20232024"

# Get comprehensive stats
stats = client.get_comprehensive_player_stats(mcdavid_id, season)

print(f"Goals: {stats['summary']['goals']}")
print(f"Assists: {stats['summary']['assists']}")
print(f"Points: {stats['summary']['points']}")
print(f"Hits: {stats['realtime']['hits']}")
print(f"Power Play Goals: {stats['powerplay']['powerPlayGoals']}")
```

### Example 2: Team Comparison

```python
# Compare team power play effectiveness
pp_stats = client.get_team_powerplay_stats("20232024")

# Sort by power play percentage
pp_stats_sorted = pp_stats.sort_values('powerPlayPct', ascending=False)

print("Top 5 Power Play Teams:")
print(pp_stats_sorted[['teamFullName', 'powerPlayPct', 'powerPlayGoals']].head())
```

### Example 3: Export Data

```python
# Export comprehensive player data to Excel
import pandas as pd

# Get various stats
summary = client.get_skater_stats_by_season("20232024", limit=500)
realtime = client.get_skater_realtime_stats("20232024", limit=500)
powerplay = client.get_skater_powerplay_stats("20232024", limit=500)

# Create Excel file with multiple sheets
with pd.ExcelWriter('nhl_stats_2023-24.xlsx') as writer:
    summary.to_excel(writer, sheet_name='Summary', index=False)
    realtime.to_excel(writer, sheet_name='RealTime', index=False)
    powerplay.to_excel(writer, sheet_name='PowerPlay', index=False)
```

### Example 4: Schedule Analysis

```python
# Analyze today's games
schedule = client.get_schedule_now()

if schedule and 'gameWeek' in schedule:
    for day in schedule['gameWeek']:
        if day.get('games'):
            for game in day['games']:
                away = game['awayTeam']['placeName']['default']
                home = game['homeTeam']['placeName']['default']
                print(f"{away} @ {home}")
```

## Season ID Format

Season IDs follow the format `YYYYYYYY` where the first four digits are the start year and the last four are the end year:

- `20232024` = 2023-24 season
- `20222023` = 2022-23 season
- `20212022` = 2021-22 season

## Player ID

Player IDs are unique NHL identifiers. You can find them:

1. From the NHL website URLs
2. Using the roster endpoints
3. From existing data exports

Example: Connor McDavid's ID is `8478402`

## Error Handling

The client includes comprehensive error handling:

```python
try:
    stats = client.get_player_season_stats(player_id, season_id)
except Exception as e:
    print(f"Error retrieving stats: {e}")
```

## Rate Limiting

The client respects NHL API rate limits. If you're making many requests, consider:

- Adding delays between requests
- Using bulk endpoints when available
- Caching frequently accessed data

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Make sure to:

1. Add tests for new functionality
2. Update documentation
3. Follow existing code style
4. Add examples for new features

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Disclaimer

This library is not officially affiliated with the NHL. It provides access to publicly available NHL data through their APIs. Please use responsibly and in accordance with NHL's terms of service.

## Changelog

### Version 1.0.0
- Initial release
- Complete player statistics support
- Goalie statistics
- Team statistics
- Schedule and standings
- Data export functionality
- Comprehensive examples

## Support

If you encounter any issues or have questions:

1. Check the [examples](examples/) directory
2. Open an issue on GitHub
3. Read the API documentation above

## Acknowledgments

- NHL for providing public APIs
- The Python community for excellent libraries
- Contributors to the NHL API documentation project 
