# 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](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 |