shipp-sports 0.1.0
Real-time sports data for NBA, MLB, and Soccer via Shipp.ai
License: MIT
Requires Python: >=3.9
Keywords: live-scores, mlb, nba, real-time, shipp, soccer, sports

# shipp-sports

Real-time sports data skill for Claude Code, powered by [Shipp.ai](https://shipp.ai).

## What This Skill Does

`shipp-sports` gives Claude access to live sports data across three major sport
categories: **NBA** (basketball), **MLB** (baseball), and **Soccer** (global
football). It combines Shipp.ai's real-time event feeds with curated external
data sources to deliver comprehensive sports intelligence.

**Live data via Shipp.ai:**
- Real-time scores for in-progress games
- Daily and upcoming game schedules
- Play-by-play event streams (cursor-based polling)

**Enriched data via external sources:**
- Player statistics and season averages
- Team rosters and depth charts
- League standings and tables
- Injury reports and roster moves

## Supported Sports and Leagues

| Sport    | Shipp Param | Leagues / Competitions                                    |
|----------|-------------|-----------------------------------------------------------|
| NBA      | `nba`       | NBA regular season, playoffs, All-Star                    |
| MLB      | `mlb`       | MLB regular season, spring training, postseason           |
| Soccer   | `soccer`    | Premier League, La Liga, Champions League, and more       |

## Setup

### 1. Get Your Shipp.ai API Key

1. Go to [platform.shipp.ai](https://platform.shipp.ai)
2. Create an account or sign in
3. Navigate to **Settings > API Keys**
4. Generate a new key
5. Set the environment variable:

```bash
export SHIPP_API_KEY="your-api-key-here"
```

### 2. (Optional) Football-Data.org API Key

For soccer standings and team data enrichment:

1. Register at [football-data.org](https://www.football-data.org/client/register)
2. The free tier provides 10 requests/minute
3. Set the environment variable:

```bash
export FOOTBALL_DATA_API_KEY="your-key-here"
```

### 3. Install Dependencies

```bash
pip install requests
```

No other dependencies are required. The skill uses only the Python standard
library plus `requests`.

## Usage Examples

### NBA

```
"What are tonight's NBA scores?"
"Show me live play-by-play for the Celtics game"
"What are LeBron's stats this season?"
"Who's injured on the Warriors?"
"Give me the current NBA standings race"
```

### MLB

```
"When do pitchers and catchers report for spring training?"
"Show me today's MLB schedule"
"What's the Yankees' 40-man roster?"
"Who are the top prospects in spring training?"
"Give me injury updates for the Dodgers"
```

### Soccer

```
"What are today's Premier League scores?"
"Show me the La Liga standings"
"When is the next Champions League match?"
"Give me live play-by-play for the Arsenal match"
"What's the current Premier League table?"
```

## Data Available Per Sport

### NBA (Mid-Season — February 2026)

| Data Point          | Source        | Availability        |
|---------------------|---------------|---------------------|
| Live scores         | Shipp.ai      | Real-time (polling) |
| Game schedule       | Shipp.ai      | Daily / upcoming    |
| Play-by-play        | Shipp.ai      | Live games          |
| Player stats        | balldontlie   | Season / career     |
| Injury reports      | Public feeds  | Updated daily       |

### MLB (Spring Training Starting — February 2026)

| Data Point          | Source              | Availability        |
|---------------------|---------------------|---------------------|
| Live scores         | Shipp.ai            | Real-time (polling) |
| Game schedule       | Shipp.ai            | Daily / upcoming    |
| Play-by-play        | Shipp.ai            | Live games          |
| Player stats        | MLB Stats API       | Season / career     |
| Rosters             | MLB Stats API       | Current 40-man      |
| Injury reports      | Public feeds        | Updated daily       |

### Soccer (Leagues in Progress — February 2026)

| Data Point          | Source              | Availability        |
|---------------------|---------------------|---------------------|
| Live scores         | Shipp.ai            | Real-time (polling) |
| Game schedule       | Shipp.ai            | Daily / upcoming    |
| Play-by-play        | Shipp.ai            | Live matches        |
| Standings           | football-data.org   | Updated per matchday|
| Team data           | football-data.org   | Current season      |

## Architecture

```
User Query
    |
    v
shipp_wrapper.py  (unified entry point)
    |
    +---> sports_data.py     (Shipp.ai: live scores, schedule, play-by-play)
    |
    +---> external_sources.py (balldontlie, MLB Stats API, football-data.org)
    |
    v
Merged Response with Source Attribution
```

The wrapper tries Shipp.ai first for live/schedule data, then enriches or
falls back to external sources for stats, standings, and injury data.

## API Reference

### Shipp.ai Endpoints Used

| Method | Endpoint                        | Purpose                    |
|--------|---------------------------------|----------------------------|
| POST   | `/connections/create`           | Create a sport connection  |
| POST   | `/connections/{id}`             | Poll for events            |
| GET    | `/connections`                  | List active connections    |
| GET    | `/sports/{sport}/schedule`      | Get game schedule          |

### External Endpoints Used

| API               | Base URL                              | Auth Required |
|-------------------|---------------------------------------|---------------|
| balldontlie       | `https://api.balldontlie.io/v1`       | No            |
| MLB Stats API     | `https://statsapi.mlb.com/api/v1`     | No            |
| football-data.org | `https://api.football-data.org/v4`    | Yes (free)    |

## Error Handling

The skill handles all standard error scenarios:

- **400 Bad Request**: Invalid parameters — logs and returns helpful message
- **401 Unauthorized**: Invalid API key — prompts for reconfiguration
- **402 Payment Required**: Plan limit reached — notifies user
- **429 Rate Limited**: Automatic exponential backoff with retry
- **5xx Server Error**: Retry with backoff, fall back to external sources

## Documentation

- Shipp.ai Docs: [docs.shipp.ai](https://docs.shipp.ai)
- Shipp.ai Platform: [platform.shipp.ai](https://platform.shipp.ai)
- API Reference: [docs.shipp.ai/api](https://docs.shipp.ai/api)

## License

This skill is part of the Shipp.ai branded skill collection.