gamechanger-client 0.0.12
An easy-to-use wrapper for interacting with the GameChanger APIs
Requires Python: >=3.9

# GameChanger Python Client

An easy-to-use, community-driven Python SDK for interacting with the [GameChanger](https://gc.com) APIs.

Automate the collection of player stats, videos, standings, and more from GameChanger. This library is designed for developers, analysts, and enthusiasts who want to programmatically access GameChanger data.

---

## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [API Overview](#api-overview)
- [Authentication](#authentication)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)

---

## Features
- Simple, Pythonic interface to GameChanger APIs
- Retrieve teams, players, stats, videos, and more
- Customizable HTTP session with retries and error handling
- Extensible endpoint structure
- Actively tested with `pytest`

---

## Installation

The package is available on PyPI:

```bash
pip install gamechanger-client
```

Or, to install the latest development version:

```bash
git clone https://github.com/TheAlanNix/gamechanger-client.git
cd gamechanger-client
pip install .
```

---

## Quick Start

```python
from gamechanger_client import GameChangerClient

# You can pass your token directly, or set the GC_TOKEN environment variable
client = GameChangerClient(token="YOUR_GC_TOKEN")

# Get your teams
teams = client.me.teams()
print(teams)

# Get players for a team
team_id = teams['teams'][0]['id']
players = client.teams.players(team_id)
print(players)
```

---

## API Overview

The main entrypoint is `GameChangerClient`, which provides access to all endpoints:

```python
from gamechanger_client import GameChangerClient
client = GameChangerClient(token="YOUR_GC_TOKEN")

# Endpoints
client.clips         # Video clips
client.events        # Event-related data
client.game_streams  # Game streams and events
client.me            # Your user/account info
client.organizations # Organization data
client.players       # Player-related data
client.public        # Public data
client.search        # Search endpoints
client.teams         # Team-related data
```

Each endpoint exposes methods for interacting with the corresponding API routes. See the [examples](#examples) below.

---

## Authentication

Currently, you must provide a valid GameChanger token. You can either:

- Pass it directly to the client:
  ```python
  client = GameChangerClient(token="YOUR_GC_TOKEN")
  ```
- Or set it as an environment variable:
  ```bash
  export GC_TOKEN=your_token_here
  ```

> **Note:** If you need help obtaining your token, please open an issue or discussion on GitHub.

---

## Finding IDs

GameChanger uses various IDs to reference different resources. Here's how to find them based on common workflows:

### Team IDs

Get team IDs from your account:

```python
teams = client.me.teams()
team_id = teams[0]['id']              # Internal team ID
team_public_id = teams[0]['public_id']  # Public team ID
team_name = teams[0]['name']
```

**When to use each:**
- `team_id` - Most API endpoints (season_stats, schedule, game_summaries, etc.)
- `public_id` - Public endpoints like `client.teams.public_players(team_public_id)`

### Organization IDs

Find organizations through search:

```python
# Search for an organization by name, location, and season
search_results = client.search.search(
    name='SLL AA',
    types=['org_league'],
    seasons=[{"name": "fall", "year": 2025}],
    sport='baseball',
    city='Smyrna',
    states=['GA']
)
organization_id = search_results['hits'][0]['result']['id']

# Then get all teams in that organization
teams = client.organizations.teams(organization_id)
```

### Event IDs

Events represent games. Get them from a team's schedule:

```python
schedule = client.teams.schedule(team_id)

# Filter for completed or scheduled games
games = [s for s in schedule if s['event']['event_type'] == 'game']
event_id = games[0]['event']['id']

# Use event IDs to get game-specific stats
game_stats = client.teams.event_player_stats(team_id, event_id)
```

### Game Stream IDs

Game streams contain play-by-play data. You can get the best game stream ID directly from an event:

```python
# Get the best game stream ID for an event
best_stream = client.events.best_game_stream_id(event_id)
game_stream_id = best_stream.get('game_stream_id')

if game_stream_id:
    # Get detailed play-by-play events
    events = client.game_streams.events(game_stream_id)
```

Alternatively, find them through game summaries:

```python
# Get game summaries for a team
game_summaries = client.teams.game_summaries(team_id)

# Find the specific game by event_id
game_summary = [g for g in game_summaries if g['event_id'] == event_id][0]
game_stream_id = game_summary.get('game_stream', {}).get('id')

if game_stream_id:
    # Get detailed play-by-play events
    events = client.game_streams.events(game_stream_id)
```

### Player IDs

Get player IDs from team rosters:

```python
# For public player data (requires public_id)
players = client.teams.public_players(team_public_id)
player_id = players[0]['id']
player_name = f"{players[0]['first_name']} {players[0]['last_name']}"
player_number = players[0]['number']

# Player IDs are then used to access stats from season_stats or event_player_stats
season_stats = client.teams.season_stats(team_id)
player_stats = season_stats['stats_data']['players'][player_id]['stats']
```

> **Tip:** See the `examples/` directory for complete working scripts showing these ID discovery patterns in action.

---

## Examples

The `examples/` directory contains complete, working scripts that demonstrate common use cases:

- **[game_stream_data.py](examples/game_stream_data.py)** - Retrieve play-by-play game stream data for a specific game
- **[team_hitting_stats.py](examples/team_hitting_stats.py)** - Export season-long hitting statistics to CSV
- **[team_pitching_stats.py](examples/team_pitching_stats.py)** - Export season-long pitching statistics to CSV
- **[team_hitting_stats_by_game.py](examples/team_hitting_stats_by_game.py)** - Export hitting stats for a specific game to CSV
- **[organization_pitching_stats.py](examples/organization_pitching_stats.py)** - Export league-wide pitching statistics across all teams to CSV

Each example includes detailed comments explaining the API calls and data structure. These are great starting points for building your own tools.

### Quick Examples

#### Get Team Stats
```python
team_id = "your_team_id"
stats = client.teams.season_stats(team_id)
print(stats)
```

#### Get Player Family Relationships
```python
player_id = "your_player_id"
relationships = client.players.family_relationships(player_id)
print(relationships)
```

#### Download Clips
```python
clips = client.clips.clips(team_id)
for clip in clips['clips']:
    print(clip['title'], clip['id'])
```

---

## Contributing

Contributions are **very welcome**! If you have ideas, bugfixes, or want to add new endpoints, please:

1. Fork the repository
2. Create a new branch (`git checkout -b feature/your-feature`)
3. Make your changes and add tests
4. Run the test suite with `pytest`
5. Submit a pull request with a clear description

If you have questions or want to discuss ideas, open an issue or start a discussion.

**Ways to contribute:**
- Add new endpoints or features
- Improve documentation
- Report or fix bugs
- Help with authentication improvements
- Write or improve tests

---

## License

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

---

## Links & Acknowledgements
- [GameChanger](https://gc.com)
- [PyPI: gamechanger-client](https://pypi.org/project/gamechanger-client/)
- [GitHub Issues](https://github.com/TheAlanNix/gamechanger-client/issues)

---

*This project is not affiliated with or endorsed by GameChanger. It is a community effort to make their data more accessible for developers.*