Metadata-Version: 2.4
Name: altsportsdata
Version: 3.0.2
Summary: Production-grade alternative sports data feed — odds, events, futures, settlement for 30 leagues
Author-email: AltSportsData <dev@altsportsdata.com>
License-Expression: MIT
Project-URL: Homepage, https://altsportsdata.com
Project-URL: Documentation, https://api.altsportsdata.com/public/docs/swagger
Project-URL: Repository, https://github.com/altsportsdata/altsportsdata-python
Project-URL: Issues, https://github.com/altsportsdata/altsportsdata-python/issues
Keywords: sports,betting,odds,sportsbook,api,sdk,alternative-sports,futures,events,altsportsdata,prediction-market,kalshi,polymarket,dfs,prizepicks,wsl,sls,f1,pbr,mma,esports,settlement
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Classifier: Framework :: AsyncIO
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: async
Requires-Dist: httpx>=0.24.0; extra == "async"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"

# AltSportsData SDK

[![PyPI](https://img.shields.io/pypi/v/altsportsdata.svg)](https://pypi.org/project/altsportsdata/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

**Production-grade alternative sports data feed — odds, events, futures, settlement for 30 leagues.**

Original model-generated probabilities for sports nobody else can price.
Built for prediction markets, DFS platforms, and sportsbooks.

```
pip install altsportsdata
```

---

## Quick Start

```python
from altsportsdata import AltSportsData

client = AltSportsData(api_key="your_key")

# Every response is a DataFrame — just use .df
events = client.list_events(status="upcoming")
events.df.head()
```

```
  league  name                        start_date            status
0 spr     Indianapolis                2026-03-07T12:00:00Z  UPCOMING
1 wsl     Pipe Masters                2026-12-09T04:00:00Z  UPCOMING
2 f1      Australian Grand Prix       2026-03-06T00:00:00Z  UPCOMING
3 wsl     Peniche                     2026-10-15T01:00:00Z  UPCOMING
4 dgpt    Queen City Classic          2026-03-20T00:00:00Z  UPCOMING
```

```python
# Odds — straight to DataFrame
odds = client.get_moneylines(events[0].id)
odds.df[["athlete", "odds", "probability"]].head()
```

```
           athlete      odds  probability
0        Eli Tomac  2.023575      49.4175
1  Hunter Lawrence  2.661776      37.5689
2       Ken Roczen  4.257294      23.4891
3      Cooper Webb  6.841256      14.6172
4     Joey Savatgy 16.204041       6.1713
```

```python
# Filter, analyze, export — it's a DataFrame
df = odds.df
favorites = df[df["probability"] > 10]     # top contenders
df.to_csv("odds.csv")                      # export
df.groupby("status").size()                # aggregate

# Events by league
events.df.groupby("league").size().sort_values(ascending=False)
```

```
league
wsl             34
f1              24
masl            24
jaialai         21
worldoutlaws    17
```

### Simple Iteration (also works)

```python
for player in odds:
    print(f"{player.name}: {player.odds:.2f}  ({player.probability:.1f}%)")
```

---

## For Prediction Markets (Kalshi, Polymarket)

Probabilities as 0–1, ready for contract creation.

```python
client = AltSportsData(api_key="your_key", odds_format="probability")
wsl = client.get_league("wsl")

odds = wsl.get_market_probabilities(event_id)
for player in odds:
    print(f"{player.name}: {player.probability}")
```

```
Eli Tomac: 0.4942
Hunter Lawrence: 0.3757
Ken Roczen: 0.2349
Cooper Webb: 0.1462
```

```python
# DataFrame — ready for contract pricing
df = odds.df
df[["athlete", "probability", "outcome_id"]]
```

### Settlement for Contract Resolution

```python
result = client.get_settlement(event_id)
for name, mkt in result["markets"].items():
    for o in mkt.get("winners", []):
        print(f"  ✅ {o['athlete']} — settled at {result['settled_at']}")
```

---

## For DFS Platforms (PrizePicks, Underdog)

```python
client = AltSportsData(api_key="your_key")

# Head-to-head matchups — ready for pick'em
matchups = client.get_matchups(event_id)
for m in matchups:
    print(f"{m.player1} ({m.odds1:.2f})  vs  {m.player2} ({m.odds2:.2f})")
```

```
Cooper Webb (2.31)  vs  Ken Roczen (1.57)
Eli Tomac (1.66)  vs  Hunter Lawrence (2.13)
```

```python
# Or get a DataFrame
df = matchups.df
df.to_csv("matchups.csv")
```

---

## For Sportsbooks (DraftKings, Bet365, Stake)

```python
# American odds
client = AltSportsData(api_key="your_key", odds_format="american")
odds = client.get_moneylines(event_id)
print(odds)

# Fractional odds (UK books)
client = AltSportsData(api_key="your_key", odds_format="fractional")
```

---

## Odds Format Conversion

Set once on the client — all responses auto-convert:

```python
client = AltSportsData(api_key="key", odds_format="probability")  # Kalshi
client = AltSportsData(api_key="key", odds_format="american")     # DraftKings
client = AltSportsData(api_key="key", odds_format="decimal")      # Stake (default)
client = AltSportsData(api_key="key", odds_format="fractional")   # Bet365
```

Or convert individual values:

```python
from altsportsdata import convert_odds

convert_odds(2.50, "decimal", "american")     # → 150.0
convert_odds(2.50, "decimal", "probability")  # → 0.4
convert_odds(150, "american", "decimal")      # → 2.5
convert_odds("3/2", "fractional", "probability")  # → 0.4
```

---

## Async Client (Production Infrastructure)

```python
from altsportsdata import AsyncAltSportsData
import asyncio

async def main():
    async with AsyncAltSportsData(api_key="key", odds_format="probability") as client:
        wsl = client.get_league("wsl")
        events = await wsl.list_events(status="upcoming")
        
        # Batch fetch — all events concurrently
        ids = [e.id for e in events[:20]]
        batch = await client.get_odds_batch(ids, "moneyline")
        for eid, odds in batch.items():
            if "error" not in odds:
                print(f"{eid}: {len(odds.get('eventWinner', []))} outcomes")

asyncio.run(main())
```

Requires: `pip install altsportsdata[async]`

---

## Enterprise Reliability

Built for production — automatic retry, rate limit handling, request tracing.

```python
client = AltSportsData(
    api_key="key",
    max_retries=3,        # exponential backoff on 429, 5xx
    retry_backoff=0.5,    # base delay in seconds
    timeout=30,           # per-request timeout
)
```

- Automatic exponential backoff with jitter on 429/5xx
- Respects `Retry-After` headers
- Request IDs (`X-Request-ID`) for debugging
- Thread-safe session management
- Context manager support: `with AltSportsData(...) as client:`

---

## Full API Reference

### Setup

```python
from altsportsdata import AltSportsData

# General client
client = AltSportsData(api_key="your_key")

# League-scoped — auto-filters everything
wsl = client.get_league("wsl")
f1  = client.get_league("f1")
spr = client.get_league("spr")

# With options
client = AltSportsData(
    api_key="your_key",
    league="wsl",
    odds_format="probability",
    max_retries=3,
)
```

### Leagues & Market Types

```python
leagues = client.list_leagues()
print(leagues)        # clean table
df = leagues.df       # pandas DataFrame

# League details
info = client.get_league_info("f1")
print(f"{info.name}: {info.market_count} markets — {info.market_types}")

# All market types
client.list_market_types()
# → ['eventWinner', 'exactasEvent', 'fastestLap', 'headToHead', ...]

# Market catalog with event counts
for lg in client.get_market_catalog():
    print(f"{lg['league']:12} {lg['name']:30} upcoming={lg['upcoming_events']}")
```

### Events

```python
events = client.list_events(status="upcoming")        # ResultSet with .df
events = client.list_events(status="live")
events = client.list_events(status="completed")
events = client.list_events(status=["live", "upcoming"])

print(events)        # clean table
df = events.df       # pandas DataFrame
events.to_csv("events.csv")

event = client.get_event("event_id")
participants = client.get_participants("event_id")
```

### Markets (one call, prices included)

```python
markets = client.get_markets()                              # upcoming (default)
markets = client.get_markets(status="live")                 # live
markets = client.get_markets(status="completed")            # settled
markets = client.get_markets(status=["live", "upcoming"])   # all active

print(markets)       # clean table
df = markets.df      # pandas DataFrame
```

### Odds (per event) — all return `OddsResult` with `.df`

```python
# Sportsbook
odds = client.get_moneylines("event_id")    # event winner
odds = client.get_matchups("event_id")      # head-to-head
odds = client.get_totals("event_id")        # over/under
odds = client.get_exactas("event_id")       # exacta
odds = client.get_podiums("event_id")       # top-3
odds = client.get_heat_winners("event_id")  # heat winner
odds = client.get_fastest_lap("event_id")   # fastest lap

# Prediction market
odds = client.get_market_probabilities("event_id")
odds = client.get_podium_probabilities("event_id")
odds = client.get_top_finish_probabilities("event_id", top_n=5)

# DFS
odds = client.get_player_props("event_id")
odds = client.get_player_matchups("event_id")
odds = client.get_player_totals("event_id", stat="points")

# Generic — any market by name or alias
odds = client.get_odds("event_id", "moneyline")

# Every OddsResult has .df
print(odds)          # clean table
df = odds.df         # pandas DataFrame
odds.to_csv("odds.csv")
```

### Batch Operations

```python
# Fetch odds for many events in parallel
events = client.list_events(league="spr", status="upcoming")
ids = [e.id for e in events]
batch = client.get_odds_batch(ids, "moneyline", max_concurrent=5)
```

### Settlement

```python
result = client.get_settlement("event_id")
# → {event_id, event_name, league, status, settled_at,
#    markets: {eventWinner: {outcomes, winners}, headToHead: {...}}}
```

### Live Polling

```python
# Generator-based live odds feed
for update in client.poll_odds(event_id, "moneyline", interval=5, max_polls=60):
    print(update)
```

### Futures

```python
client.list_futures()
client.get_futures(tour="tour_id", type="winner")
```

### Odds Conversion (Static)

```python
AltSportsData.convert(2.50, "decimal", "american")     # → 150.0
AltSportsData.convert(2.50, "decimal", "probability")  # → 0.4
```

---

## 30 Leagues

| Code | League | Code | League |
|------|--------|------|--------|
| `wsl` | World Surf League | `pbr` | Professional Bull Riders |
| `sls` | Street League Skateboarding | `bkfc` | Bare Knuckle FC |
| `f1` | Formula 1 | `motogp` | MotoGP |
| `spr` | Supercross | `mxgp` | MXGP |
| `nrx` | Nitrocross | `jaialai` | Jai Alai |
| `fdrift` | Formula Drift | `nll` | National Lacrosse League |
| `masl` | Major Arena Soccer | `nhra` | NHRA Drag Racing |
| `powerslap` | Power Slap | `dgpt` | Disc Golf Pro Tour |
| `worldoutlaws` | World of Outlaws | `usac` | USAC Racing |
| `xgame` | X Games | `motoamerica` | MotoAmerica |
| `hlrs` | High Limit Racing | `byb` | BYB Extreme Fighting |
| `athletesunlimited` | Athletes Unlimited | `lux` | LUX Fight League |
| `raf` | Real American Freestyle | `mltt` | Major League Table Tennis |
| `motocrs` | Motocross | `spectation` | Spectation |
| `gsoc` | Global Soccer | `sprmtcrs` | Supermotocross |

---

## Links

- [API Docs](https://api.altsportsdata.com/public/docs)
- [Swagger](https://api.altsportsdata.com/public/docs/swagger)

## License

MIT
