soccer-match-tracker 0.1.0
Live soccer match tracking for Premier League, La Liga, Champions League, and MLS
License: MIT
Requires Python: >=3.9
Keywords: champions-league, football, la-liga, live-scores, premier-league, shipp, soccer

# soccer-match-tracker

**Your complete football companion across the world's top leagues.**

Live scores, standings, fixtures, and match events for Premier League, La Liga,
Champions League, and MLS -- all in one place.

## The Problem

Following football across multiple leagues means juggling different apps,
websites, and time zones. Premier League on one tab, La Liga on another,
Champions League results buried somewhere else. When matches overlap, it is
nearly impossible to keep up.

## The Solution

`soccer-match-tracker` gives you a unified view of all the football that
matters. Live scores from every league on one screen, standings updated every
matchday, upcoming fixtures for the week ahead, and goal/card/substitution
events as they happen.

### What You Get

- **Multi-league live scores**: See every active match across PL, La Liga, CL,
  and MLS grouped by competition
- **Match events feed**: Goals, red/yellow cards, substitutions, penalties --
  as they happen
- **League tables**: Current standings with points, goal difference, form
- **Fixtures calendar**: Next 7 days of upcoming matches across all leagues
- **Team squads**: Full roster lookup for any team in covered leagues

## Who This Is For

- **Multi-league fans** who follow clubs across different competitions
- **Fantasy managers** (FPL, La Liga Fantasy, UCL Fantasy) who need live data
- **Analysts** tracking league form and standings trends
- **Match-day viewers** who want a second-screen experience

## Setup

### 1. Data API Key for Live Scores (Required)

For live match scores and events:

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

Get one at [platform.shipp.ai](https://platform.shipp.ai).

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

For standings, fixtures, and team data:

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

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

### 3. Install Dependencies

```bash
pip install requests
```

## Usage

### Live Scores (All Leagues)

```python
from scripts.match_tracker import MatchTracker

tracker = MatchTracker()

# Get all live matches across leagues
live = tracker.live_scores()
print(live.display())
```

### Single League

```python
# Premier League only
pl_live = tracker.live_scores(league="PL")

# La Liga standings
la_liga = tracker.standings(league="PD")
print(la_liga.table())
```

### Upcoming Fixtures

```python
# Next 7 days across all leagues
upcoming = tracker.upcoming(days=7)
print(upcoming.display())

# Champions League only
cl_fixtures = tracker.upcoming(league="CL", days=7)
```

### Match Events

```python
# Get events for a specific match
events = tracker.match_events(match_id="some-match-id")
for event in events:
    print(f"{event['minute']}' {event['type']}: {event['player']} ({event['team']})")
```

### League Standings

```python
standings = tracker.standings(league="PL")
print(standings.table())
```

### Team Squad

```python
squad = tracker.team_squad(team_id=57)  # Arsenal
for player in squad:
    print(f"{player['name']} - {player['position']}")
```

### Full Dashboard

```python
# Everything at once
dashboard = tracker.dashboard()
print(dashboard)
```

## Output Format

### Live Scores Display

```
=== LIVE FOOTBALL SCORES ===

--- Premier League ---
  Arsenal 2 - 1 Chelsea          67'
    52' GOAL  Saka (Arsenal)
    61' GOAL  Palmer (Chelsea)
    65' GOAL  Havertz (Arsenal)

  Manchester City 0 - 0 Liverpool   34'

--- Champions League ---
  Real Madrid 1 - 0 PSG           78'
    44' GOAL  Vinicius Jr (Real Madrid)
    71' YELLOW CARD  Marquinhos (PSG)

--- La Liga ---
  Barcelona 3 - 0 Sevilla         FT
  Atletico Madrid vs Real Betis   20:00
```

### League Table

```
=== Premier League Standings ===
 #  Team                  P   W   D   L   GF  GA  GD  Pts
 1  Arsenal              26  19   4   3   58  21  +37  61
 2  Liverpool             26  18   5   3   55  25  +30  59
 3  Manchester City       26  17   4   5   56  28  +28  55
 4  Aston Villa           26  15   5   6   48  32  +16  50
 ...
```

### Upcoming Fixtures

```
=== Upcoming Fixtures (Next 7 Days) ===

Saturday, February 21
  Premier League
    Arsenal vs Manchester United      15:00
    Chelsea vs Tottenham              17:30

  La Liga
    Real Madrid vs Atletico Madrid    21:00

Sunday, February 22
  Premier League
    Liverpool vs Newcastle            16:30

  Champions League (Round of 16)
    Bayern Munich vs Inter Milan      21:00
```

## Architecture

```
match_tracker.py          Main orchestrator + display formatting
    |
    +---> football_data.py    football-data.org API integration
    |
    +---> shipp_wrapper.py    Live match score/event connection
```

## Rate Limits

| Source            | Limit                | Strategy                      |
|-------------------|----------------------|-------------------------------|
| Live data feed    | Plan-dependent       | Poll every 10-30 seconds      |
| football-data.org | 10 requests/minute   | Cache standings (5 min TTL)   |

The tracker automatically rate-limits football-data.org requests and caches
responses to stay within the free tier. Standings and fixtures are cached for
5 minutes since they change infrequently.

## License

MIT

---

<sub>Powered by [Shipp.ai](https://shipp.ai) real-time data</sub>