Sports data API covering NBA, NHL, MLB, and NFL. Provides player lookups by jersey number,
team information, upcoming game schedules, and per-user team preferences.
Base URL: https://api.league-trac.com
Interactive Docs →
OpenAPI Spec →
Auth Token Setup →
Authentication
All endpoints except /health, /get_logo, and /docs
require a Bearer token.
Authorization: Bearer <token>
- Tokens issued by Authentik, expire after 10 minutes
- Obtain a token:
auth-token league-trac
- Config:
~/.config/auth-token.env - set AUTHENTIK_URL and LEAGUE_TRAC_CLIENT_ID
Supported Leagues
nba
nhl
mlb
nfl
Endpoints
System
| Method | Path | Auth | Description |
|---|
| GET | /health | No | Public health check (uptime monitoring) |
| GET | /internal/health | Yes | Detailed health: DB status, latency, uptime, user |
| GET | /debug/whoami | Yes | Returns auth context (user, claims) |
Players
| Method | Path | Description |
|---|
| GET | /player/{league}/{jersey} | Player from user's preferred team by jersey number. Optional ?search_name= to override team. |
| GET | /player/{league}/{team_code}/{jersey} | Player by explicit team code + jersey. e.g. /player/nhl/pit/87 |
| GET | /active_player/{league}/{jersey} | Active player from user's favorite team. |
| GET | /active_opposition_player/{league}/{jersey} | Player from the team that last played against user's favorite team. |
| GET | /search_players?name={last_name} | Search by last name. Optional: ?league=nhl, ?first_name=jack. Returns match_type (exact/partial) + results array. |
Teams
| Method | Path | Description |
|---|
| GET | /team_codes/{league} | All team codes for a league. Returns array of {team_code, team_location, team_name}. |
Preferences
| Method | Path | Description |
|---|
| GET | /get_preferences | Returns {nba_favorite, nhl_favorite, mlb_favorite, nfl_favorite} (full team names). |
| PUT | /set_preferences | Body: {"nba_favorite":"lakers","nhl_favorite":"rangers",...}. Returns resolved full team names. Errors on no match or multiple matches. |
| GET | /get_preferred_api_team_id/{league} | Returns {api_team_id, team_code} for user's preferred team in that league. |
Games
| Method | Path | Description |
|---|
| GET | /get_upcoming?days=4&date=YYYY-MM-DD | Upcoming games based on preferences. MLB/NBA/NHL: favorite team only. NFL: all Thu/Sat/Mon games + Sunday games for favorite team. |
Assets
| Method | Path | Auth | Description |
|---|
| GET | /get_logo/{league}/{location}/{name} | No | Returns SVG team logo. e.g. /get_logo/nba/LosAngeles/Lakers |
Admin
| Method | Path | Description |
|---|
| POST | /admin/cleanup_games?days=2&dry_run=false | Delete game records older than N days. Use dry_run=true to preview. |
Example Requests
# Get a token
TOKEN=$(auth-token league-trac)
# Upcoming games (next 7 days)
curl -H "Authorization: Bearer $TOKEN" \
"https://api.league-trac.com/get_upcoming?days=7"
# Player by preferred team + jersey
curl -H "Authorization: Bearer $TOKEN" \
"https://api.league-trac.com/player/nba/23"
# Player by explicit team + jersey
curl -H "Authorization: Bearer $TOKEN" \
"https://api.league-trac.com/player/nhl/pit/87"
# Opponent player lookup
curl -H "Authorization: Bearer $TOKEN" \
"https://api.league-trac.com/active_opposition_player/nhl/7"
# Search players by last name
curl -H "Authorization: Bearer $TOKEN" \
"https://api.league-trac.com/search_players?name=hughes&league=nhl"
# Set preferences
curl -X PUT -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"nba_favorite":"lakers","nhl_favorite":"rangers"}' \
"https://api.league-trac.com/set_preferences"
# All NHL team codes
curl -H "Authorization: Bearer $TOKEN" \
"https://api.league-trac.com/team_codes/nhl"
Error Codes
| Status | Meaning |
|---|
400 | Bad request - missing or invalid parameter |
401 | Missing or invalid Bearer token |
404 | Player, team, or preference not found |
503 | Service degraded - database unreachable |
Contact
Email: [email protected]
License: Internal / Partner Use Only
