ESPN Provider
ESPN is the primary data provider (priority 0), serving 52 pre-configured leagues plus 240+ dynamically discovered soccer leagues. The API is free, public, and requires no authentication.
API Details
| Base URL | https://site.api.espn.com/apis/site/v2/sports |
| Auth | None required |
| Rate Limit | Generous (practically impossible to hit — DNS throttling is the usual bottleneck) |
Key Endpoints
| Endpoint | Description |
|---|---|
/{sport}/{league}/scoreboard?dates={YYYYMMDD} | Games on a specific date |
/{sport}/{league}/teams/{team_id}/schedule | Team schedule |
/{sport}/{league}/teams/{team_id} | Team details |
/{sport}/{league}/summary?event={event_id} | Event details and scores |
/{sport}/{league}/teams | All teams in a league (cache refresh) |
HTTP Client Configuration
| Setting | Default | Env Variable |
|---|---|---|
| Max connections | 100 | ESPN_MAX_CONNECTIONS |
| Timeout | 10s | ESPN_TIMEOUT |
| Retry count | 3 | ESPN_RETRY_COUNT |
| Max workers | 100 | ESPN_MAX_WORKERS |
Retry logic uses exponential backoff: 0.5s → 1s → 2s → 4s (capped at 10s) with ±30% jitter. Rate limit (429) responses trigger longer backoff: 5s → 10s → 20s (capped at 60s), respecting the Retry-After header if present.
League ID Format
ESPN leagues are configured in schema.sql with provider_league_id in sport/league format:
football/nfl
basketball/nba
hockey/nhl
soccer/eng.1
baseball/mlb
Sports Coverage
| Sport | Leagues | Notes |
|---|---|---|
| Football | NFL, NCAAF, UFL | |
| Basketball | NBA, WNBA, G League, NCAAM, NCAAW | |
| Hockey | NHL, NCAA M/W, Olympics M/W | |
| Baseball | MLB | MiLB handled by MLB Stats provider |
| Soccer | 40+ pre-configured, 240+ discovered | Dot notation: eng.1, ger.2 |
| Combat Sports | UFC | Event Card matching |
| Lacrosse | NLL, PLL, NCAA M/W | |
| Volleyball | NCAA M/W |
Soccer League Discovery
ESPN’s API exposes 240+ soccer leagues dynamically. During cache refresh, Teamarr discovers available leagues and makes them selectable in the league picker under the Soccer sport. These discovered leagues support event matching in event groups but don’t have pre-configured team import.
Soccer leagues use ESPN’s dot notation: {country}.{tier} (e.g., eng.1 for Premier League, ger.2 for 2. Bundesliga).
Special Behaviors
- Status mapping: ESPN event statuses are normalized to Teamarr’s internal
scheduled,in_progress,final,postponed,cancelled - Team ID corrections: Hardcoded mapping for known ESPN data mismatches (e.g., some women’s hockey teams)
- Tournament sports: Golf, tennis, and racing events have no home/away teams — parsed via
TournamentParserMixin - UFC: Parsed via
UFCParserMixinwith fighter name extraction from the core API
File Locations
| File | Purpose |
|---|---|
teamarr/providers/espn/provider.py | ESPNProvider class |
teamarr/providers/espn/client.py | HTTP client with retry logic |
teamarr/providers/espn/constants.py | Status mapping |
teamarr/providers/espn/tournament.py | TournamentParserMixin (golf, tennis, racing) |
teamarr/providers/espn/ufc.py | UFCParserMixin |