README

Official PHP client for the footballdata.io API — football/soccer fixtures, live scores, predictions, standings, odds, team & player stats, and FIFA rankings.

• Zero required runtime dependencies — uses the bundled curl extension directly (no Guzzle).
• PHP 8.0+
• PSR-4 autoloading under the Footballdata\ namespace.

Get a free API key at footballdata.io/signup.

Install

composer require voroxi/footballdata

30-second quickstart

<?php

require 'vendor/autoload.php';

use Footballdata\Client;
use Footballdata\FootballDataException;

$client = new Client('YOUR_API_KEY');

try {
    // Today's fixtures
    $fixtures = $client->fixtures->today(['limit' => 10]);

    // A league table
    $standings = $client->leagues->standings(1625);

    // Rate-limit / plan info from the last response
    echo $client->lastMeta['requests_remaining'] ?? 'n/a', " requests left\n";
} catch (FootballDataException $e) {
    echo "[{$e->getStatus()}] {$e->getErrorCode()}: {$e->getMessage()}\n";
}

Every method returns the parsed data payload as an associative array (or null when the endpoint has no body). The SDK does not impose field-level models — you work with the raw API data.

Configuration

$client = new Client('YOUR_API_KEY', [
    'baseUrl' => 'https://footballdata.io/api/v1', // default
    'timeout' => 30,                               // seconds, default 30
]);

Rate-limit info

After any successful call, the response meta (plan, requests_used, requests_limit, requests_remaining, …) is available on the client:

$meta = $client->lastMeta;      // or $client->getLastMeta()
echo $meta['plan'], ' ', $meta['requests_remaining'];

Resources & examples

Methods are grouped by resource. Optional filters and pagination are passed as a trailing options array (e.g. ['page' => 2, 'limit' => 50]).

meta

$client->meta->status();     // GET /meta/status
$client->meta->coverage();   // GET /meta/coverage

account

$client->account->usage();   // GET /account/usage

fixtures

$client->fixtures->today(['league_id' => 1625, 'status' => 'NS']); // GET /fixtures/today
$client->fixtures->todayPredictions();                              // GET /fixtures/today/predictions
$client->fixtures->live();                                          // GET /fixtures/live
$client->fixtures->upcoming(['page' => 1, 'limit' => 20]);          // GET /fixtures/upcoming
$client->fixtures->results(['page' => 1]);                          // GET /fixtures/results

leagues

$client->leagues->list(['country' => 'England', 'search' => 'premier']); // GET /leagues
$client->leagues->standings(1625);   // GET /leagues/{id}/standings
$client->leagues->matches(1625);     // GET /leagues/{id}/matches
$client->leagues->teams(1625);       // GET /leagues/{id}/teams
$client->leagues->seasons(1625);     // GET /leagues/{id}/seasons
$client->leagues->stats(1625);       // GET /leagues/{id}/stats
$client->leagues->btts(1625);        // GET /leagues/{id}/btts
$client->leagues->corners(1625);     // GET /leagues/{id}/corners

matches

$client->matches->list(['page' => 1, 'limit' => 50]); // GET /matches
$client->matches->get(9876543);           // GET /matches/{id}
$client->matches->stats(9876543);         // GET /matches/{id}/stats
$client->matches->events(9876543);        // GET /matches/{id}/events
$client->matches->odds(9876543);          // GET /matches/{id}/odds
$client->matches->predictions(9876543);   // GET /matches/{id}/predictions
$client->matches->probabilities(9876543); // GET /matches/{id}/probabilities
$client->matches->btts(9876543);          // GET /matches/{id}/btts
$client->matches->corners(9876543);       // GET /matches/{id}/corners
$client->matches->byDate('2026-05-10');   // GET /matches/date/{date}

teams

$client->teams->list(['search' => 'arsenal']); // GET /teams
$client->teams->get(59);            // GET /teams/{id}
$client->teams->matches(59);        // GET /teams/{id}/matches
$client->teams->players(59);        // GET /teams/{id}/players
$client->teams->stats(59);          // GET /teams/{id}/stats
$client->teams->h2h(59, 66);        // GET /teams/{id}/h2h/{opponentId}

players

$client->players->list(['search' => 'saka']); // GET /players
$client->players->get(12345);   // GET /players/{id}
$client->players->stats(12345); // GET /players/{id}/stats

seasons

$client->seasons->list();          // GET /seasons
$client->seasons->matches(2024);   // GET /seasons/{id}/matches
$client->seasons->standings(2024); // GET /seasons/{id}/standings
$client->seasons->teams(2024);     // GET /seasons/{id}/teams

countries

$client->countries->list();               // GET /countries
$client->countries->leagues('England');   // GET /countries/{country}/leagues

fifaRankings

$client->fifaRankings->list();              // GET /fifa-rankings
$client->fifaRankings->current();           // GET /fifa-rankings/current
$client->fifaRankings->periods();           // GET /fifa-rankings/periods
$client->fifaRankings->history('Brazil');   // GET /fifa-rankings/{country}/history

search

$client->search('arsenal'); // GET /search?q=arsenal

Error handling

Any non-2xx response raises a Footballdata\FootballDataException carrying the full context from the API error envelope:

use Footballdata\FootballDataException;

try {
    $data = $client->matches->predictions(9876543);
} catch (FootballDataException $e) {
    $e->getStatus();     // HTTP status: 401, 403, 404, 429, ...
    $e->getErrorCode();  // machine-readable code from the API
    $e->getMessage();    // human-readable message
    $e->getDetails();    // raw details array (may be null)

    // On a 403 plan-gate, the API includes an upgrade hint:
    if ($upgrade = $e->getUpgrade()) {
        echo "Upgrade to {$upgrade['plan_name']} ({$upgrade['price']}): {$upgrade['upgrade_url']}\n";
    }
}

Transport failures (DNS, connection, timeout) also raise a FootballDataException with getStatus() === 0 and error code network_error.

Requirements

• PHP >= 8.0
• ext-curl, ext-json (both bundled with a standard PHP build)

Links

• Website & docs: https://footballdata.io
• Get a free API key: https://footballdata.io/signup
• Issues: https://github.com/voroxi/footballdata-php/issues

License

MIT © 2026 Voroxi Group LLC — see LICENSE.