# 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/)

**The data feed for alternative sports betting.**

One SDK. 31 leagues. Every market type. Built for sportsbooks, DFS platforms, and prediction markets.

```
pip install altsportsdata
```

## 30 Seconds to Your First Odds

```python
from altsportsdata import AltSportsData

wsl = AltSportsData(api_key="sk_live_xxx", league="wsl")

# What's live right now?
events = wsl.list_events(status="live")

# Pull moneylines
odds = wsl.get_moneylines(events[0].id)

# Build a parlay
parlay = wsl.calculate_parlay(events[0].id, picks=["odd_1", "odd_2", "odd_3"])
print(f"Combined odds: {parlay['combinedOdds']}")
```

## Why AltSportsData

| Problem | Solution |
|---------|----------|
| Alt sports data is fragmented across dozens of sources | **One unified API** — 31 leagues, standardized schema |
| Your team wastes weeks integrating each new sport | **Minutes to integrate** — same SDK, same patterns |
| No odds available for niche sports your users want | **Full market coverage** — moneylines, matchups, props, totals, futures, parlays |
| Existing feeds don't support your platform's format | **Sportsbook-native naming** — use the terms your team already knows |

## Sportsbook-Native API

Use the names your trading team already knows. We alias everything.

```python
# These all work — use whatever your team prefers
wsl.get_moneylines("evt_id")       # → eventWinner
wsl.get_matchups("evt_id")         # → headToHead
wsl.get_player_props("evt_id")     # → propBets
wsl.get_totals("evt_id")           # → overUnder
wsl.get_exactas("evt_id", n=3)     # → eventExacta

# Or use API-native names directly
wsl.get_odds("evt_id", "eventWinner")
wsl.get_odds("evt_id", "headToHead")
```

## Full API Reference

### Setup

```python
from altsportsdata import AltSportsData

# Lock to a league — all queries auto-filter
wsl = AltSportsData(api_key="sk_live_xxx", league="wsl")
f1  = AltSportsData(api_key="sk_live_xxx", league="f1")
pbr = AltSportsData(api_key="sk_live_xxx", league="pbr")

# Or query across all leagues
client = AltSportsData(api_key="sk_live_xxx")
```

### Leagues

```python
client.list_leagues()     # all leagues with markets & tours
client.list_sports()      # alias
```

### Events

```python
# Filter by status — use plain English
client.list_events(status="upcoming")
client.list_events(status="live")
client.list_events(status="completed")
client.list_events(status=["live", "upcoming"])

# Date range
client.list_events(start_date="2024-04-01T00:00:00Z", end_date="2024-04-30T00:00:00Z")

# Single event
client.get_event("evt_id")

# Participants / athletes
client.get_participants("evt_id")

# Heat scores (action sports & racing)
client.get_heat_scores("evt_id", "heat_id")
```

### Odds

```python
# Sportsbook-native
client.get_moneylines("evt_id")                          # event winner
client.get_matchups("evt_id")                             # head-to-head
client.get_player_props("evt_id")                         # prop bets
client.get_totals("evt_id")                               # over/under
client.get_totals("evt_id", sub_market="points")          # with sub-market
client.get_heat_winners("evt_id")                         # heat winner (WSL/SLS/racing)
client.get_fastest_lap("evt_id")                          # fastest lap (racing)
client.get_exactas("evt_id", n=2)                         # exacta (2/3/4-way)
client.get_podiums("evt_id")                              # podium finish
client.get_shows("evt_id")                                # shows
client.get_dream_team("evt_id")                           # dream team

# Generic — pass any market type
client.get_odds("evt_id", "moneyline")                    # alias resolves automatically
client.get_odds("evt_id", "eventWinner")                  # API-native also works
client.get_odds("evt_id", "raceTop5")                     # all 17 market types supported
```

**17 market types:** `moneyline` · `matchups` · `props` · `totals` · `heat_winner` · `fastest_lap` · `exacta` · `podium` · `shows` · `dream_team` · `top3` · `top5` · `top10` · `second_place` · `hole_shot` · `multi_ou` · `heat_exacta`

### Parlays (SGP)

```python
parlay = client.calculate_parlay("evt_id", picks=["odd_1", "odd_2", "odd_3"])
# → {"combinedOdds": 12.5, "combinedProbability": 0.08, "selections": [...]}
```

### Futures

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

### Jai Alai

```python
client.get_jaialai_matches("evt_id")
client.get_jaialai_odds("evt_id")    # moneyline, spread, totals per set
```

## 31 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 |
| `nrx` | Nitrocross | `mxgp` | MXGP |
| `fdrift` | Formula Drift | `jaialai` | Jai Alai |
| `masl` | Major Arena Soccer | `nll` | National Lacrosse League |
| `powerslap` | Power Slap | `nhra` | NHRA Drag Racing |
| `dgpt` | Disc Golf Pro Tour | `worldoutlaws` | World of Outlaws |
| `byb` | BYB Extreme Fighting | `gsoc` | Global Soccer |
| `usac` | USAC Racing | `xgame` | X Games |
| `motocrs` | Motocross | `motoamerica` | MotoAmerica |
| `sprmtcrs` | Supermotocross | `hlrs` | Haulers |
| `spr` | Supercross | `cdc` | CDC |
| `athletesunlimited` | Athletes Unlimited | `lux` | Lux |
| `raf` | RAF | `mltt` | Major League Table Tennis |
| `spectation` | Spectation | | |

## Error Handling

```python
from altsportsdata import AltSportsData, AuthenticationError, RateLimitError, NotFoundError

try:
    odds = wsl.get_moneylines("evt_id")
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Event not found")
except RateLimitError as e:
    print(f"Rate limited — retry in {e.retry_after}s")
```

## Coming Soon

- **TypeScript SDK** — same flat API, same aliases
- **Go SDK** — for high-throughput pipelines
- **WebSocket feeds** — real-time odds streaming
- **Webhook push** — odds delivered to your endpoint
- **Pandas integration** — `client.get_moneylines("evt_id", as_df=True)`

## Links

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

## License

MIT
