TheSportsDB (TSDB) is a community-driven sports data API used as a fallback provider (priority 100) for leagues not covered by ESPN — including Australian sports, rugby, cricket, boxing, CFL, and Scandinavian leagues.
API details
| |
|---|
| Base URL | https://www.thesportsdb.com/api/v1/json/{api_key}/{endpoint} |
| Auth | API key in URL path (123 for free tier) |
| Priority | 100 (last resort) |
| Rate limit | 30 req/min free, 100 req/min premium |
API tiers
The free tier uses API key 123 (the default). It is suitable for leagues with low event volume.| Limit | Value |
|---|
| Rate limit | 30 req/min |
| Events per query | 5 per day per league |
| Team search | 10 teams |
| Cost | Free |
A premium key unlocks full event coverage and higher rate limits.| Limit | Value |
|---|
| Rate limit | 100 req/min |
| Events per query | Full coverage |
| Team search | 3,000 teams |
| Cost | ~$9/month |
Configuring a premium API key
Add your premium key in Settings > System > TheSportsDB API Key. The key takes effect immediately — no restart required.
The league picker shows a crown icon on premium-tier leagues and warns you if you select one without a key configured.
Supported leagues
| League | Code | TSDB ID | Sport | Tier |
|---|
| Canadian Football League | cfl | 4405 | Football | Free |
| Unrivaled | unrivaled | 5622 | Basketball | Free |
| Norwegian Fjordkraft-ligaen | norwegian-hockey | 4926 | Hockey | Free |
| Boxing | boxing | 4445 | Boxing | Free |
| Australian Football League | afl | 4456 | Australian Football | Premium |
| National Rugby League | nrl | 4416 | Rugby | Premium |
| Super Rugby Pacific | super-rugby | 4551 | Rugby | Premium |
| Indian Premier League | ipl | 4460 | Cricket | Premium |
| Big Bash League | bbl | 4461 | Cricket | Premium |
| SA20 | sa20 | 5532 | Cricket | Premium |
| Svenska Cupen | svenska-cupen | 4756 | Soccer | Premium |
schema.sql:
| Column | Used by | Example |
|---|
provider_league_id | eventsnextleague.php, lookupleague.php | 5159 |
provider_league_name | eventsday.php, search_all_teams.php | Canadian OHL |
search_all_leagues.php to discover correct values.
Event resolution
TSDB uses a three-step fallback chain when fetching events:
eventsday.php — date-specific lookup (primary, works for most leagues)eventsnextleague.php — upcoming events filtered by date (fallback)eventsround.php — full round/season events filtered by date (last resort, used for leagues like Unrivaled)
Rate limiting
Teamarr enforces rate limits preemptively using a sliding window limiter — it tracks request timestamps and waits before approaching the limit, rather than waiting for 429 responses.
If the API returns HTTP 429, Teamarr retries with exponential backoff: 5s → 10s → 20s → 40s → 80s.
Rate limit statistics (total requests, preemptive waits, reactive waits) are tracked and available for UI feedback.
Cache TTLs
| Data | TTL |
|---|
| Teams | 24 hours |
| Next events | 1 hour |
| Past games | 7 days |
| Today’s games | 30 minutes |
| Tomorrow’s games | 4 hours |
| 3–7 days out | 8 hours |
| 8+ days out | 24 hours |
File locations
| File | Purpose |
|---|
teamarr/providers/tsdb/provider.py | TSDBProvider class |
teamarr/providers/tsdb/client.py | HTTP client with preemptive rate limiting |