Skip to content


Repository files navigation

TheSportsDB PHP library

Build Packagist Version Coverage Status PHPStan Level GitHub

An easy-to-use PHP library to get data from


  • Get data for lists, livescores, lookups, schedules, searches or video highlights
  • Get results in serialized classes
  • Use your own API key
  • Throttle long-running scripts
  • Use PSR-4 autoloading
  • Supports PHP 7.4+

This library uses Semantic Versioning.


Install this PHP library with Composer.

> composer require nkl-kst/the-sports-db


Get data

Get sports data from TheSportsDB.

// You need to load the Composer autoload file somewhere in your code before
require_once 'vendor/autoload.php';

use NklKst\TheSportsDb\Client\ClientFactory;

// Create a client
$client = ClientFactory::create();

// Get soccer livescores
$livescores = $client->livescore()->now('Soccer');
echo $livescores[0]->strProgress;

// Get video highlights
$highlights = $client->highlight()->latest();
echo $highlights[0]->strVideo;

// Get next events for Liverpool FC
$events = $client->schedule()->teamNext(133602);
echo $events[0]->strEvent;

See integration tests for examples of all documented API calls.

Use your API key

Use your own Patreon API key.

use NklKst\TheSportsDb\Client\ClientFactory;

// Set an API key
$client = ClientFactory::create();

Throttle requests

You are advised to do no more than 100 requests per minute to TheSportsDB API (the hard limit is two requests per second). If you have long-running scripts to gather many data, please consider to use the built-in rate limiter.

use NklKst\TheSportsDb\Client\ClientFactory;

// Use the default rate limit of 100 requests per minute
$client = ClientFactory::create();

// Do your requests as usual

// You can unset the rate limiter later

As this library uses the Symfony Rate Limiter Component, it's possible to use a custom rate limit mechanism. Please consult the Symfony documentation for more information.

Known issues

  • Livescores for v1 are not supported.
  • If you are getting an exception like JSON property "foo" in class "Bar" must not be NULL, then there is an entity attribute which should be nullable. Please open a new issue in this case.


If you have any problems or questions, feel free to open an issue or a pull request.

Developer notes

Run tests and code checks.

# Unit tests
> composer test-unit

# Integration tests (API calls, Patreon key required)
> PATREON_KEY=<YOUR_PATREON_KEY> composer test-integration
# On Windows use 'set PATREON_KEY=<YOUR_PATERON_KEY>' before running the tests

# Analyze code (static analysis)
> composer analyze-code

# Check code (coding standards)
> composer check-code

License: MIT