espn-sports-api

Python client for ESPN's public API. No authentication required for most endpoints.

Installation

uv add espn-sports-api

or with pip:

pip install espn-sports-api

Quick Start

from espn_sports_api import NFL, NBA, Soccer, SeasonType, quick_scores

# One-liner for today's scores
scores = quick_scores("nba")

# Get today's NFL scores
nfl = NFL()
scores = nfl.today()

# Get NBA team roster
nba = NBA()
roster = nba.team_roster("lal")

# Get Premier League table
epl = Soccer(league="epl")
table = epl.standings()

Supported Sports

Common Methods

All sport classes share these methods:

# Scoreboard with filtering
sport.scoreboard(dates="20240115")  # By date
sport.scoreboard(season=2024, week=10)  # By season/week
sport.scoreboard(seasontype=SeasonType.POSTSEASON)  # or raw int: 1=pre, 2=reg, 3=post

# Teams
sport.teams()  # All teams
sport.team("NYY")  # Team details
sport.team_roster("NYY")  # Team roster
sport.team_schedule("NYY")  # Team schedule
sport.team_injuries("NYY")  # Team injuries

# League-wide data
sport.injuries()  # All injuries
sport.transactions()  # Trades, signings, IR moves
sport.statistics()  # League statistics
sport.leaders()  # Statistical leaders
sport.venues()  # Stadium information
sport.franchises()  # Franchise data
sport.events()  # All games
sport.positions()  # All positions

# Other
sport.standings()  # Standings
sport.news()  # News articles
sport.event("401547417")  # Game details
sport.playbyplay("401547417")  # Play-by-play data
sport.athlete("12345")  # Athlete profile
sport.athlete_stats("12345")  # Athlete statistics
sport.seasons(2024)  # Season information

# Date convenience methods
sport.today()  # Today's games
sport.yesterday()  # Yesterday's games
sport.tomorrow()  # Tomorrow's games
sport.live()  # In-progress games only
sport.on_date(date(2024, 12, 25))  # Games on specific date
sport.date_range(start, end)  # Games in date range
sport.for_week(10, season=2024)  # Games for specific week

Soccer fixtures

from datetime import date
from espn_sports_api import Soccer

epl = Soccer(league="epl")
matches = epl.on_date(date(2026, 10, 10))
weekend = epl.date_range(date(2026, 10, 10), date(2026, 10, 12))
arsenal = epl.team_schedule("359", fixtures=True)

Scoreboard events include kick-off dates, match status, scores and goal details. If ESPN blocks a soccer scoreboard request with HTTP 403, the client retries through ESPN's CDN and returns the same scoreboard structure. Other HTTP errors are raised normally. Failed requests are not cached as empty match days.

College Conference Filtering

Filter college sports by conference:

from espn_sports_api import NCAAF, NCAAB, NCAAFConference, Conferences

# By string name
ncaaf = NCAAF()
sec_games = ncaaf.scoreboard(conference="SEC")
big_ten = ncaaf.scoreboard(conference="Big Ten")

# By enum (type-safe)
ncaab = NCAAB()
games = ncaab.scoreboard(conference=NCAABConference.BIG_EAST)

# Lookup conference IDs
Conferences.get("ncaaf", "SEC")  # Returns 8
Conferences.get("ncaab", "Big Ten")  # Returns 7
Conferences.list_all("ncaaf")  # All NCAAF conferences

Betting Odds

Extract odds from scoreboard responses:

from espn_sports_api import NFL, Odds

nfl = NFL()
scoreboard = nfl.scoreboard()

# Get all odds
all_odds = Odds.from_scoreboard(scoreboard)
for game in all_odds:
    print(f"{game.away_team} @ {game.home_team}")
    if game.spread:
        print(f"  Spread: {game.spread.favorite} {game.spread.spread}")
    if game.moneyline:
        print(f"  ML: {game.moneyline.home_odds}/{game.moneyline.away_odds}")
    if game.total:
        print(f"  O/U: {game.total.over_under}")

# Or get specific data
spreads = Odds.spreads(scoreboard)
moneylines = Odds.moneylines(scoreboard)
totals = Odds.totals(scoreboard)

Data Models

Parse API responses into dataclasses:

from espn_sports_api import NFL, parse_injuries, parse_teams

nfl = NFL()

# Parse injuries - models have readable __str__ methods
injury_response = nfl.injuries()
injuries = parse_injuries(injury_response)
for injury in injuries:
    print(injury)  # "John Doe (QB, Patriots): Questionable - Ankle"

# Parse teams
teams_response = nfl.teams()
teams = parse_teams(teams_response)
for team in teams:
    print(f"{team.name} ({team.abbreviation})")

Available models: Venue, Broadcast, Weather, Injury, Transaction, Athlete, Team

Soccer Leagues

90+ leagues supported:

from espn_sports_api import Soccer

# Major leagues
epl = Soccer(league="epl")
la_liga = Soccer(league="la_liga")
bundesliga = Soccer(league="bundesliga")
serie_a = Soccer(league="serie_a")
ligue_1 = Soccer(league="ligue_1")
mls = Soccer(league="mls")

# Cups and competitions
champions_league = Soccer(league="champions_league")
europa_league = Soccer(league="europa_league")
fa_cup = Soccer(league="fa_cup")
copa_libertadores = Soccer(league="copa_libertadores")
world_cup = Soccer(league="world_cup")

# International
liga_mx = Soccer(league="liga_mx")
eredivisie = Soccer(league="eredivisie")
scottish_premiership = Soccer(league="scottish_premiership")
j_league = Soccer(league="j_league")

# All available leagues
print(Soccer.available_leagues())

# Filter leagues by region
print(Soccer.list_leagues("eng"))  # English leagues only

# Cross-league scoreboard
all_scores = Soccer.all_leagues_scoreboard(dates="20240115")

Racing

from espn_sports_api import Racing

f1 = Racing(series="f1")
nascar = Racing(series="nascar")
indycar = Racing(series="indycar")

standings = f1.standings()
schedule = f1.schedule(season=2024)

Fantasy Leagues

from espn_sports_api import FantasyFootball

# Public league
league = FantasyFootball(league_id=123456, season=2024)

# Private league (requires cookies)
league = FantasyFootball(
    league_id=123456, season=2024, swid="{YOUR-SWID}", espn_s2="YOUR_ESPN_S2_COOKIE"
)

teams = league.teams()
matchups = league.matchups(week=1)
standings = league.standings()

Caching

Enable response caching for faster repeated requests:

from espn_sports_api import ESPNClient, NFL
from pathlib import Path

# Memory cache with 5-minute TTL
client = ESPNClient(cache_ttl=300)
nfl = NFL(client=client)

# First request hits the API
scores = nfl.scoreboard()  # ~300ms

# Second request uses cache
scores = nfl.scoreboard()  # ~0ms

# Clear cache when needed
client.clear_cache()

# Disk cache for persistence across sessions
client = ESPNClient(cache_ttl=3600, cache_dir=Path("./cache"))

Context Manager

with NFL() as nfl:
    scores = nfl.scoreboard()

Examples

See the examples/ directory for scripts and an interactive notebook:

python examples/scripts/nfl_example.py
python examples/scripts/soccer_epl_example.py

Error Handling

All API errors raise typed exceptions:

from espn_sports_api import NFL, ESPNNotFoundError, ESPNRateLimitError, ESPNTimeoutError

nfl = NFL()
try:
    nfl.athlete("invalid_id")
except ESPNNotFoundError:
    print("Athlete not found")
except ESPNRateLimitError:
    print("Rate limited, back off")
except ESPNTimeoutError:
    print("Request timed out")

Exception hierarchy: ESPNApiError (base) > ESPNNotFoundError, ESPNRateLimitError, ESPNServerError, ESPNTimeoutError, ESPNResponseError.

Automatic retries (3x with backoff) are enabled by default for 429 and 5xx responses.

API Reference

ESPN's public API doesn't require authentication. Base URLs:

• site.api.espn.com - Scoreboards, teams, standings, news, injuries, transactions
• sports.core.api.espn.com - Athletes, venues, franchises, events, leaders
• site.web.api.espn.com - Athlete statistics
• lm-api-reads.fantasy.espn.com - Fantasy leagues

License

MIT