client
Table of Contents
Interfaces
- ResponseCache
- Stores raw response bodies. Keys never contain an API key.
- Clock
- Time source for rate limiting, retries and timing. Replace it in tests to avoid real waits.
- Transport
- Performs GET requests. Implement it to use another HTTP stack (e.g. a PSR-18 client) or to
fake the network in tests. Throw TransportException when no response arrives; return every
HTTP status, including 4xx and 5xx, as a Response.
Classes
- CachePolicy
- Time-to-live in seconds for each Freshness. Zero or less means don't cache.
- InMemoryResponseCache
- A bounded, per-process LRU cache with per-entry expiry.
- Psr16ResponseCache
- Caches responses in any PSR-16 cache (Redis, APCu, files...). Needs psr/simple-cache.
- Config
- Client settings. Pass them to SportsDb's constructor as named arguments.
- ApiMessageException
- The API answered with a message instead of data: an unrecognised {"Message": ...} body, or a
rejected parameter, which v1 reports as text where the records belong:
{"seasons": "Invalid League ID passed"}.
- HttpStatusException
- Any other non-2xx HTTP response, after retries for 5xx.
- InvalidApiKeyException
- The API rejected the key (HTTP 400 "Invalid Premium API key"). Only 123, 3 and paid keys work.
- NetworkException
- No HTTP response arrived (DNS, connection, timeout), after retries.
- PremiumRequiredException
- A v2 endpoint was called with a free key. v2 accepts premium keys only. Thrown before any request.
- RateLimitException
- HTTP 429 after the retry was used up or disabled.
- ResponseParseException
- The body was not a TheSportsDB envelope (e.g. an HTML error page).
- SportsDbException
- Base class for every exception this library throws. Messages never contain an API key:
v1 URLs (which carry the key in their path) are shown with *** in its place.
- Helpers
- 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.
- CurlTransport
- The default transport, on ext-curl.
- Response
- TransportException
- Thrown by a Transport when no HTTP response arrived. The client retries, then throws NetworkException.
- ApiRecord
- Base class of every record the API returns (Team, Event, ...).
- Contract
- A player's contract (`lookupcontracts.php`, `lookup/player_contracts`).
- Country
- A country (`all_countries.php`, `all/countries`). v1 returns only [name] and [flag32].
- Equipment
- A team kit (`lookupequipment.php`, `lookup/team_equipment`).
- Event
- A game, match, race or other event. Also used for video highlights.
- EventResult
- One competitor's result in an individual-sport event: a race, a golf tournament, a
fight. Returned both per player (`playerresults.php`) and per event (`eventresults.php`).
- EventStat
- One team statistic for an event, home vs away (`lookupeventstats.php`, `lookup/event_stats`).
- FormerTeam
- A team a player used to play for (`lookupformerteams.php`, `lookup/player_teams`).
- Honour
- A trophy a player won (`lookuphonours.php`, `lookup/player_honours`).
- League
- A league or cup. Lists (`all_leagues.php`, v2 `search/league`) fill only a few fields;
look it up by id for the rest.
- LeagueRef
- A league a team plays in: one of idLeague/strLeague .. idLeague7/strLeague7.
- LineupEntry
- One player in an event's lineup (`lookuplineup.php`, `lookup/event_lineup`).
- LiveScore
- A game in progress (`livescore.php`, `livescore/...`).
- Milestone
- A career milestone or award (`lookupmilestones.php`, `lookup/player_milestones`).
- Player
- A player, manager or other person. Search and list endpoints fill only some fields;
look the player up by id for the rest.
- PlayerExternalIds
- Ids of the same player in other databases.
- PlayerStat
- One statistic for a player in one season (`lookupplayerstats.php`, `lookup/player_stats`).
- Season
- A season of a league (`search_all_seasons.php`, `list/seasons`).
- SeasonPoster
- One season poster or badge uploaded for a league (v2 `list/seasonposters`). A season can have
several; each is a separate piece of artwork with its own id.
- Socials
- Web and social links. TheSportsDB often gives these without a scheme (www.facebook.com/Arsenal).
- Sport
- A sport (`all_sports.php`, `all/sports`).
- Standing
- One row of a league table (`lookuptable.php`). v1 only; there is no v2 equivalent.
- Team
- A team. Search and list endpoints fill only some fields (v2 `list/teams` has no
alternate names, for example); a lookup by id fills them all.
- TimelineEntry
- A goal, card or substitution during an event (`lookuptimeline.php`, `lookup/event_timeline`).
- TvListing
- One broadcast of an event on one channel (v1 `lookuptv.php`/`eventstv.php`, v2 `lookup/event_tv`/`filter/tv`).
- Venue
- A stadium, arena or circuit.
- RequestEvent
- One finished API call, passed to Config::$requestListener.
- SportsDb
- The TheSportsDB client.
- SystemClock
- Lists
- Lists.
- Live
- Live scores on v1: **undocumented** but answering, including the full feed for free keys.
- Lookup
- Lookups by id.
- Schedule
- Schedules and results. Event times are UTC.
- Search
- Search endpoints. Free keys: one result each.
- Tv
- TV listings. Free keys: 1 per call.
- V1Api
- The v1 API: https://www.thesportsdb.com/api/v1/json/{key}/{endpoint}.php
- Video
- All
- all/...: complete catalogues.
- Lists
- list/.
- Live
- livescore/.... Not cached unless the cache policy says so. Entries can be stale: check updated.
- Lookup
- lookup/...: full records by id.
- Schedule
- schedule/.... Event times are UTC.
- Search
- search/...: up to about 10 results, summary fields only. Ids arrive as JSON numbers here.
- Tv
- filter/tv/.
- V2Api
- The v2 API: https://www.thesportsdb.com/api/v2/json/{group}/{name}/{param}, key in the
X-API-KEY header. **Premium keys only**: with a free key every call throws
PremiumRequiredException without touching the network.
Enums
- Freshness
- How quickly an endpoint's data changes. Every endpoint is tagged with one.
- EventStatus
- A broad reading of a strStatus code, so you don't need every sport's codes. Covers the codes in
TheSportsDB's data documentation (docs_api_data) for every sport.
- ImageSize
- Image sizes TheSportsDB serves by appending a path suffix.
- RoundStage
- The stage a special intRound value stands for (docs_api_data). Other values are ordinary round numbers.