thesportsdb-client/io.github.rohang27.thesportsdb/Helpers

Helpers

Common tasks in one call. Each helper picks the best endpoint for your key: v2 with a premium key, v1 with the free key 123 (and then the free key's small result limits apply, as noted on each method). Any key other than 123 that the API accepts is a paid key, so no extra call is made to find out.

Returned events are sorted by start time (events without a time last).

Functions

currentSeason

suspend fun currentSeason(leagueId: Long): String?

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

eventChannels

suspend fun eventChannels(eventId: Long): List<TvListing>

The channels showing an event. Free key: at most 2.

eventsOnLocalDate

suspend fun eventsOnLocalDate(date: LocalDate, zone: ZoneId, sport: String? = null, leagueId: Long? = null): List<Event>

Events on a calendar day in your time zone. The API files events under their UTC date, so a local day can span two API days; this fetches both and keeps the events that start on date in zone. Optionally narrowed to a sport or a leagueId. Free key: at most 3 events per UTC day.

leagueTeams

suspend fun leagueTeams(leagueId: Long): List<Team>

A league's teams, with badges. Premium: one call. Free key: the league's name is looked up, then up to 10 teams.

liveScores

suspend fun liveScores(sport: String? = null, leagueId: Long? = null): List<LiveScore>

Games in progress, optionally for one sport (e.g. Soccer) or one leagueId. Premium: v2 live scores. Free key: v1's undocumented live feed, which needs a sport; for a league, the league's sport is looked up and the results filtered.

recentLeagueResults

suspend fun recentLeagueResults(leagueId: Long): List<Event>

A league's latest results. Premium: up to about 20. Free key: 1.

roundEvents

suspend fun roundEvents(leagueId: Long, round: Int, season: String? = null): List<Event>

Every event in one round (matchday) of a season (season defaults to the current one). Premium: filtered from the season schedule. Free key: v1's undocumented eventsround.php, which returns the whole round (premium keys get 404 from it, hence the two routes).

seasonEvents

suspend fun seasonEvents(leagueId: Long, season: String? = null): List<Event>

Every event of a league's season (season defaults to the current one). Premium: the whole season in one call. Free key: only the first 5 events.

teamSchedule

suspend fun teamSchedule(teamId: Long): List<Event>

A team's schedule across all competitions, past and future. Premium: the full schedule (one call). Free key: the next and the last event only, and only home games (a free-key limit).

tvListings

suspend fun tvListings(country: String, sport: String? = null, days: Int = 7, from: LocalDate = LocalDate.now(ZoneOffset.UTC)): List<TvListing>

A country's TV listings for the next days days from from, optionally for one sport. Premium: about a week of the country's listings in one call, filtered here. Free key: one call per day, which needs a sport, and returns 1 listing per call.

upcomingLeagueEvents

suspend fun upcomingLeagueEvents(leagueId: Long, days: Int = 7, from: LocalDate = LocalDate.now(ZoneOffset.UTC)): List<Event>

A league's events starting in the next days UTC days, beginning with from. Premium: filtered from the season schedule (one or two calls). Free key: one eventsday call per day, each limited to 3 events.