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 |
| Priority | 0 (tried first) |
| Rate limit | Generous — 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) |
sport/league path format in the provider_league_id column in schema.sql:
football/nfl
basketball/nba
hockey/nhl
soccer/eng.1
baseball/mlb
{country}.{tier} (e.g., eng.1 for the Premier League, ger.2 for 2. Bundesliga).
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 the 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 queries ESPN to discover available leagues and makes them selectable in the league picker under the Soccer sport.
Discovered leagues support event matching in event groups but do not have pre-configured team import. Only the 40+ pre-configured soccer leagues support team import.
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-After header if present.
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
UFCParserMixin with 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 |