thesportsdb-client

Helpers
in package

FinalYes

Common tasks in one call. Each helper uses v2 with a premium key and v1 with a free key (then the free keys' small limits apply). Any key other than the free keys that the API accepts is a paid key, so no extra call is made to find out. Events come back sorted by start time.

Table of Contents

Properties

$db  : SportsDb

Methods

currentSeason()  : string|null
A league's current season name, e.g. "2026-2027"; null if the league is unknown.
eventChannels()  : array<int, TvListing>
eventsOnLocalDate()  : array<int, Event>
Events starting on $day in time zone $tz. The API files events under their UTC date, so a local day can span two API days; this fetches each UTC day it overlaps and keeps the events that start on the local day. Free keys: at most 3 events per UTC day.
leagueTeams()  : array<int, Team>
liveScores()  : array<int, LiveScore>
Games in progress. Premium: v2. Free keys: v1's undocumented feed, which needs a sport; for a league, its sport is looked up and the feed filtered. Entries can be stale: check $updated.
recentLeagueResults()  : array<int, Event>
roundEvents()  : array<int, Event>
One round (matchday). Premium: filtered from the season. Free keys: eventsround.php (undocumented; the whole round). Premium keys get 404 from that endpoint, hence two routes.
seasonEvents()  : array<int, Event>
teamSchedule()  : array<int, Event>
tvListings()  : array<int, TvListing>
A country's TV listings for $days days. Premium: the country's week in one call, filtered.
upcomingLeagueEvents()  : array<int, Event>
Events in the next $days UTC days from $start (default: today, UTC). Premium: filtered from the season. Free keys: one eventsday.php call per day (3 events a day).
byStart()  : array<int, Event>
compareTimes()  : int
days()  : array<int, DateTimeImmutable>
distinct()  : array<int, Event>
premium()  : bool

Properties

Methods

currentSeason()

A league's current season name, e.g. "2026-2027"; null if the league is unknown.

public currentSeason(int $leagueId) : string|null
Parameters
$leagueId : int
Return values
string|null

eventChannels()

public eventChannels(int $eventId) : array<int, TvListing>
Parameters
$eventId : int
Return values
array<int, TvListing> —

the channels showing an event. Free keys: at most 2.

eventsOnLocalDate()

Events starting on $day in time zone $tz. The API files events under their UTC date, so a local day can span two API days; this fetches each UTC day it overlaps and keeps the events that start on the local day. Free keys: at most 3 events per UTC day.

public eventsOnLocalDate(DateTimeInterface|string $day, DateTimeZone $tz[, string|null $sport = null ][, int|null $leagueId = null ]) : array<int, Event>
Parameters
$day : DateTimeInterface|string

a date (only Y-m-d is used)

$tz : DateTimeZone
$sport : string|null = null
$leagueId : int|null = null
Return values
array<int, Event>

leagueTeams()

public leagueTeams(int $leagueId) : array<int, Team>
Parameters
$leagueId : int
Return values
array<int, Team> —

a league's teams with badges. Free keys: looks up the league name, then up to 10 teams.

liveScores()

Games in progress. Premium: v2. Free keys: v1's undocumented feed, which needs a sport; for a league, its sport is looked up and the feed filtered. Entries can be stale: check $updated.

public liveScores([string|null $sport = null ][, int|null $leagueId = null ]) : array<int, LiveScore>
Parameters
$sport : string|null = null
$leagueId : int|null = null
Return values
array<int, LiveScore>

recentLeagueResults()

public recentLeagueResults(int $leagueId) : array<int, Event>
Parameters
$leagueId : int
Return values
array<int, Event> —

a league's latest results. Premium: about 20. Free keys: 1.

roundEvents()

One round (matchday). Premium: filtered from the season. Free keys: eventsround.php (undocumented; the whole round). Premium keys get 404 from that endpoint, hence two routes.

public roundEvents(int $leagueId, int $round[, string|null $season = null ]) : array<int, Event>
Parameters
$leagueId : int
$round : int
$season : string|null = null
Return values
array<int, Event>

seasonEvents()

public seasonEvents(int $leagueId[, string|null $season = null ]) : array<int, Event>
Parameters
$leagueId : int
$season : string|null = null
Return values
array<int, Event> —

every event of a season (default: current). Premium: one call. Free keys: the first 5.

teamSchedule()

public teamSchedule(int $teamId) : array<int, Event>
Parameters
$teamId : int
Return values
array<int, Event> —

a team's schedule. Premium: past and future, all competitions. Free keys: next + last, home games only.

tvListings()

A country's TV listings for $days days. Premium: the country's week in one call, filtered.

public tvListings(string $country[, string|null $sport = null ][, int $days = 7 ][, DateTimeInterface|null $start = null ]) : array<int, TvListing>

Free keys: one call per day, which needs a sport.

Parameters
$country : string
$sport : string|null = null
$days : int = 7
$start : DateTimeInterface|null = null
Return values
array<int, TvListing>

upcomingLeagueEvents()

Events in the next $days UTC days from $start (default: today, UTC). Premium: filtered from the season. Free keys: one eventsday.php call per day (3 events a day).

public upcomingLeagueEvents(int $leagueId[, int $days = 7 ][, DateTimeInterface|null $start = null ]) : array<int, Event>
Parameters
$leagueId : int
$days : int = 7
$start : DateTimeInterface|null = null
Return values
array<int, Event>

byStart()

private static byStart(array<int, Event> $events) : array<int, Event>
Parameters
$events : array<int, Event>
Return values
array<int, Event>

compareTimes()

private static compareTimes(DateTimeImmutable|null $a, DateTimeImmutable|null $b) : int
Parameters
$a : DateTimeImmutable|null
$b : DateTimeImmutable|null
Return values
int

days()

private static days(int $days, DateTimeInterface|null $start) : array<int, DateTimeImmutable>
Parameters
$days : int
$start : DateTimeInterface|null
Return values
array<int, DateTimeImmutable>

distinct()

private static distinct(array<int, Event> $events) : array<int, Event>
Parameters
$events : array<int, Event>
Return values
array<int, Event>

premium()

private premium() : bool
Return values
bool
On this page

Search results