Metadata-Version: 2.5
Name: endzoneapi
Version: 0.1.0
Summary: Python client for the EndzoneAPI NFL data API. No dependencies.
Project-URL: Homepage, https://endzoneapi.com
Project-URL: Documentation, https://endzoneapi.com/docs
Project-URL: Repository, https://github.com/noahowsh/puckapi
Project-URL: Sign up, https://endzoneapi.com/signup
Author-email: EndzoneAPI <support@endzoneapi.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,betting,endzoneapi,nfl,odds,player-props,sports-data
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == 'pandas'
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# EndzoneAPI for Python

Python client for the [EndzoneAPI](https://endzoneapi.com) NFL data API. It has no required dependencies (standard library only) and works on Python 3.9 and newer. Pandas is optional.

## Install

```bash
pip install endzoneapi
pip install "endzoneapi[pandas]"   # only if you want DataFrames
```

## Set your key

Get a free key at https://endzoneapi.com/signup. Free accounts get 500 credits a month.

```bash
export ENDZONEAPI_API_KEY=your_key_here
```

```python
from endzoneapi import Client

client = Client()                      # reads ENDZONEAPI_API_KEY
client = Client(api_key="your_key")    # or pass it in
```

## Examples

### 1. Player props for one game

`get_player_props` returns every player's line, by sportsbook, for one market. Pass `estimate_only=True` first to see the credit cost without being charged.

```python
from endzoneapi import Client, to_dataframe

client = Client()

print(client.get_player_props(game_id="2025_01_KC_LAC", estimate_only=True))

props = client.get_player_props(
    game_id="2025_01_KC_LAC",
    market="player_pass_yds",
    bookmaker="draftkings",
)
df = to_dataframe(props, key="props")
print(df[["player_name", "line", "over_odds", "under_odds"]])
```

### 2. Props for every game in a week

Loop over a week of games and stack the results. This is the usual shape of a props model's data pull.

```python
import pandas as pd
from endzoneapi import Client, to_dataframe

client = Client()

games = client.get_games(season=2025, week=1, limit=2)["games"]
frames = []
for game in games:
    props = client.get_player_props(game_id=game["game_id"], market="player_rush_yds")
    frames.append(to_dataframe(props, key="props"))
week = pd.concat(frames, ignore_index=True)
print(len(week), "lines from", len(games), "games")
print(week.groupby("bookmaker").size())
```

### 3. Find a player, then pull his stats

Player ids are GSIS ids. `search_players` finds them by name.

```python
from endzoneapi import Client

client = Client()

mahomes = client.search_players("Mahomes", limit=1)["players"][0]
stats = client.get_player_stats(mahomes["player_id"], season=2025)
print(mahomes["name"], mahomes["team"])
print(stats)
```

## Credits

Every method returns the `data` object from the response. After each call, `client.last_credits_used` and `client.last_credits_remaining` hold the counters from the `X-Credits-Used` and `X-Credits-Remaining` headers. Methods that take `estimate_only=True` return the price of a call without running or charging it.

## Pandas

```python
from endzoneapi import to_dataframe

df = to_dataframe(data)                # finds the main list in the response
df = to_dataframe(data, key="rows")    # or name the list yourself
```

Nested fields become dotted columns. Install pandas separately or with `pip install "endzoneapi[pandas]"`.

## Errors

Every error is an `APIError` subclass, with the server's message and the HTTP status.

| Exception | Status | Meaning |
| --- | --- | --- |
| `AuthError` | 401 | Missing, invalid or revoked key |
| `InsufficientCreditsError` | 402 | Not enough credits for the call |
| `NotFoundError` | 404 | The id or name does not exist |
| `RateLimitError` | 429 | Too many requests; has `.retry_after` when the server sends it |
| `APIError` | 400, 5xx | Bad arguments or a server problem |
| `APIConnectionError` | none | No response (network or timeout) |

```python
from endzoneapi import Client, APIError, InsufficientCreditsError, RateLimitError

client = Client()
try:
    data = client.list_teams()
except InsufficientCreditsError:
    print("Out of credits, top up at https://endzoneapi.com")
except RateLimitError as exc:
    print("Slow down, retry after", exc.retry_after)
except APIError as exc:
    print(exc.status_code, exc.message)
```

The client retries 429 and 5xx responses and connection failures up to 3 times with backoff, and honors `Retry-After`. Set `Client(max_retries=0)` to turn that off.

If you see `CERTIFICATE_VERIFY_FAILED` on a python.org install for macOS, run the "Install Certificates.command" script that came with Python, or `pip install certifi` (the client uses it when present).

## Options

```python
Client(
    api_key=None,                          # defaults to $ENDZONEAPI_API_KEY
    base_url="https://mcp.endzoneapi.com",           # point at another host
    timeout=60.0,                          # seconds per request
    max_retries=3,
)
```

`client.call("tool_name", {"arg": "value"})` calls any tool by name, which helps when the API adds a tool before this package does.

## Tools

Method names match the API tool names. Arguments are keyword arguments; required ones can also be passed positionally. Each method's docstring lists its arguments (`help(client.list_teams)`).

| Method | Credits | What it does |
| --- | --- | --- |
| `list_teams` | 1 | List teams |
| `get_standings` | 2 | Standings |
| `get_team_stats` | 5 | Team stats |
| `get_games` | 5 | Games |
| `get_schedule` | 2 | Schedule |
| `get_game_detail` | 10 | Game detail |
| `get_head_to_head` | 10 | Head to head |
| `search_players` | 2 | Search players |
| `get_player_stats` | 5 | Player stats |
| `get_player_leaders` | 5 | Player leaders |
| `get_injuries` | 2 | Injuries |
| `get_depth_chart` | 2 | Depth chart |
| `get_snap_counts` | 5 | Snap counts |
| `get_plays` | 10 | Plays |
| `get_advanced_stats` | 5 | Advanced stats |
| `get_odds` | 10 | Odds |
| `get_line_movement` | 25 | Line movement |
| `get_player_props` | 10 | Player props |
| `get_prop_history` | 10 | Prop history |
| `get_alt_lines` | 10 | Alt lines |

Full API reference: https://endzoneapi.com/docs

## License

MIT
