shipp-soccer 0.1.0

Live soccer match tracking for Premier League, La Liga, Champions League, and MLS

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:

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

Get one at platform.shipp.ai.

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

For standings, fixtures, and team data:

1. Register at football-data.org
2. The free tier provides 10 requests per minute
3. Set the environment variable:

export FOOTBALL_DATA_API_KEY="your-key-here"

3. Install Dependencies

pip install requests

Usage

Live Scores (All Leagues)

from scripts.match_tracker import MatchTracker

tracker = MatchTracker()

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

Single League

# 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

# 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

# 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

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

Team Squad

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

Full Dashboard

# 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

---

_{Powered by Shipp.ai real-time data}