r/nike
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
ee8436d5b8a4db8686993149c14d1e9cafe7ce99
nike/docs/sportsdb_api_v2_reference.md
Robert Helewka ee8436d5b8 feat: implement MCP server and dashboard for football data platform 
Add complete Nike football data platform with:
- FastMCP server exposing football data tools over HTTP
- RapidAPI client for free-api-live-football-data integration
- Bootstrap web dashboard with live match/standings views
- REST API endpoints for dashboard consumption
- Docker support with multi-stage build
- Comprehensive README with architecture docs
- Minimal .gitignore replacing verbose Python template
2026-03-21 18:19:42 +00:00

10 KiB
Raw Blame History

TheSportsDB API V2 — Validated Field Reference

All fields below are validated against real API responses from discovery runs with a premium key ($9/mo Patreon). Last validated: 2026-03-10.

Authentication

  • V2: X-API-KEY header
  • V1: Key in URL path: /api/v1/json/{key}/...
  • Same premium key works for both

V2 Base URL

https://www.thesportsdb.com/api/v2/json

Endpoints & Response Schemas

Search Leagues — /search/league/{name}

Wrapper key: search

Field Type Example
idLeague string "5279"
strLeague string "MLS Next Pro"
strSport string "Soccer"
strBadge string/null URL
strCountry string "United States"
strCurrentSeason string "2026"
strGender string "Male"

⚠️ V2 league search is unreliable — "MLS" returns "MLS Next Pro" (ID 5279), not "American Major League Soccer" (ID 4346). Use V1 team search + idLeague field as the authoritative source for league IDs.

Schedule (Next/Previous) — /schedule/{next|previous}/team/{teamId}

Wrapper key: schedule

Field Type Example
idEvent string "2406751"
strEvent string "FC Cincinnati vs Toronto FC"
idLeague string "4346"
strLeague string "American Major League Soccer"
strSport string "Soccer"
strHomeTeam string "FC Cincinnati"
strAwayTeam string "Toronto FC"
idHomeTeam string "136688"
idAwayTeam string "134148"
intRound string "3"
intHomeScore string/null "0"
intAwayScore string/null "1"
strTimestamp string "2026-03-08T23:00:00"
dateEvent string "2026-03-08"
dateEventLocal string "2026-03-08"
strTime string "23:00:00"
strTimeLocal string "18:00:00"
strHomeTeamBadge string URL
strAwayTeamBadge string URL
strVenue string "TQL Stadium"
strCountry string "United States"
strThumb string/null URL
strPoster string/null URL
strVideo string/null YouTube URL
strPostponed string "no"
strFilename string descriptive filename
strStatus string "Match Finished" / "Not Started"

Event Lookup — /lookup/event/{eventId}

Wrapper key: lookup

All schedule fields plus:

Field Type Example
idAPIfootball string "1490149"
strEventAlternate string "Toronto FC @ FC Cincinnati"
strFilename string descriptive
strLeagueBadge string URL
strSeason string "2026"
strDescriptionEN string ""
intSpectators null/string null
strOfficial string referee name
strGroup string ""
intScore null
intScoreVotes null
strResult string ""
idVenue string "20820"
strCity string ""
strSquare string/null URL
strFanart string/null URL
strBanner string/null URL
strMap string/null
strTweet1 string ""
strLocked string "unlocked"

Event Stats — /lookup/event_stats/{eventId}

Wrapper key: lookup

Field Type Example
idStatistic string "526548"
idEvent string "2434724"
idApiFootball string "1523412"
strEvent string "Mansfield Town vs Arsenal"
strStat string "Shots on Goal"
intHome string "5"
intAway string "8"

Known strStat values: Shots on Goal, Shots off Goal, Total Shots, Blocked Shots, Shots insidebox, Shots outsidebox, Fouls, Corner Kicks, Offsides, Ball Possession, Yellow Cards, Red Cards, Goalkeeper Saves, Total passes, Passes accurate, Passes %, expected_goals, goals_prevented.

⚠️ Not all matches have stats. MLS and smaller leagues may return {"Message": "No data found"}.

Event Timeline — /lookup/event_timeline/{eventId}

Wrapper key: lookup

Field Type Example
idTimeline string "1628218"
idEvent string "2434724"
strTimeline string "subst" / "Goal" / "Yellow Card"
strTimelineDetail string "Substitution 1" / "Normal Goal"
strHome string "Yes" / "No"
strEvent string "Mansfield Town vs Arsenal"
idAPIfootball string "1523412"
idPlayer string "34153358"
strPlayer string "Leandro Trossard"
strCutout string/null URL
idAssist string/null "34182526"
strAssist string/null "Piero Hincapié"
intTime string "38"
strPeriod string/null
idTeam string "133604"
strTeam string "Arsenal"
strComment string "NULL" (literal string, not null)
dateEvent string "2026-03-07"
strSeason string "2025-2026"

⚠️ strComment can be the literal string "NULL" — treat it as null.

Event Lineup — /lookup/event_lineup/{eventId}

Wrapper key: lookup

Field Type Example
idLineup string "864558"
idEvent string "2434724"
strEvent string "Mansfield Town vs Arsenal"
idAPIfootball string "1523412"
strPosition string "Defender"
strPositionShort string "D" / "G" / "M" / "F"
strFormation string/null
strHome string "Yes" / "No"
strSubstitute string "Yes" / "No"
intSquadNumber string "23"
strCutout string/null URL
idPlayer string "34145366"
strPlayer string "Adedeji Oshilaja"
idTeam string "134381"
strTeam string "Mansfield"
strCountry string "England"
strSeason string "2025-2026"

Squad (Roster) — /list/players/{teamId}

Wrapper key: list

Field Type Example
idPlayer string "34146036"
strPlayer string "Kevin Long"
idTeam string "134148"
strTeam string "Toronto FC"
strThumb string/null URL
strCutout string/null URL
strRender string/null URL
dateBorn string "1990-08-18"
strPosition string "Centre-Back"

⚠️ Squad list does NOT include strNumber, strNationality, strHeight, strWeight. Use /lookup/player/{id} for the full profile.

Player Detail — /lookup/player/{playerId}

Wrapper key: lookup

Field Type Example
idPlayer string "34146036"
idTeam string "134148"
idTeam2 string "0"
idTeamNational string/null
idAPIfootball string "18915"
idPlayerManager string/null
idWikidata string "Q6396794"
idTransferMkt string "111114"
idESPN string "140531"
strNationality string "Ireland"
strPlayer string "Kevin Long"
strPlayerAlternate string ""
strTeam string "Toronto FC"
strTeam2 string ""
strSport string "Soccer"
dateBorn string "1990-08-18"
dateDied null/string
strNumber string "5"
dateSigned string "2010-07-01"
strSigning string
strWage string
strBirthLocation string "Cork, Ireland"
strStatus string "Active"
strDescriptionEN string biography
strGender string "Male"
strSide string ""
strPosition string "Centre-Back"
strHeight string "188 cm"
strWeight string "183 lbs"
intLoved string "0"
strThumb string/null URL
strCutout string/null URL
strRender string/null URL
strBanner string/null URL
strLastName string "Long"

Livescores — /livescore/soccer

Wrapper key: livescore

Field Type Example
idLiveScore string "29571878"
idEvent string "2438107"
strSport string "Soccer"
idLeague string "4432"
strLeague string "Uruguayan Primera Division"
idHomeTeam string "136051"
idAwayTeam string "136052"
strHomeTeam string "Boston River"
strAwayTeam string "Liverpool Montevideo"
strHomeTeamBadge string URL
strAwayTeamBadge string URL
intHomeScore string "0"
intAwayScore string "1"
intEventScore null
intEventScoreTotal null
strStatus string "FT" / "1H" / "2H" / "HT"
strProgress string "90"
strEventTime string "00:30"
dateEvent string "2026-03-10"
updated string "2026-03-10 02:22:23"

V1 Endpoints (Supplementary)

See sportsdb_api_v1_reference.md for full V1 validated fields. Key V1-only endpoints:

Endpoint Wrapper Key Purpose
/lookuptable.php?l=&s= table League standings
/eventsday.php?d=&s= events Events by date
/eventslast.php?id= results Team's last 5 results
/eventsnext.php?id= events Team's next 5 fixtures
/searchteams.php?t= teams Team search
/searchplayers.php?p= player Player search

Important Notes

  1. All numeric values are strings — always cast with int() or handle None
  2. All IDs are strings — e.g. "134148" not 134148
  3. strComment can be literal "NULL" — not JSON null
  4. strHome/strSubstitute are "Yes"/"No" — not booleans
  5. Wrapper keys differ by endpoint — search, lookup, list, schedule, livescore, table
  6. Not all matches have stats/lineup/timeline — smaller leagues return {"Message": "No data found"}
  7. League search is unreliable on V2 — use V1 team search to discover league IDs

Verified IDs

Entity Name TheSportsDB ID
League American Major League Soccer 4346
League English Premier League 4328
Team Toronto FC 134148
Team Arsenal 133604
Reference in New Issue View Git Blame Copy Permalink