README

PHP client for the 11elo Soccer ELO API — live and historical Elo ratings for German football (Bundesliga, 2. Bundesliga, 3. Liga).

Requires PHP 8.1+ and the built-in curl and json extensions (enabled by default).

Installation

composer require chafficui/elevenelo

Quick start

<?php

require 'vendor/autoload.php';

$client = new \ElevenElo\Client('11e_fre_your_key_here');

// List all teams
$teams = $client->getTeams();
foreach ($teams as $team) {
    echo $team['teamName'] . ' ' . $team['currentElo'] . PHP_EOL;
}

// Get detailed info for one team
$team = $client->getTeam('Bayern München');
echo $team['team']['currentElo'] . PHP_EOL;

// Upcoming matches
$upcoming = $client->getUpcomingMatches(league: 'BL1', limit: 10);
foreach ($upcoming as $match) {
    echo $match['homeTeam'] . ' vs ' . $match['awayTeam'] . PHP_EOL;
}

Getting an API key

Register for free at https://www.11elo.com/docs.
Keys follow the format 11e_<tier>_<hex> and are sent via the X-API-Key request header (handled automatically by this client).

Rate limits by tier:

API reference

new Client(apiKey, baseUrl, timeout)

Teams

getTeams(): array

Returns all teams with current ELO stats, league info and trend data.

$teams = $client->getTeams();
// [['teamName' => 'Bayern München', 'currentElo' => 1847, 'league' => 'BL1', ...], ...]

getTeam(string $teamName): array

Full detail for one team — ELO history, recent form, upcoming matches, career stats.

$team = $client->getTeam('Borussia Dortmund');
// ['team' => [...], 'eloHistory' => [...], 'recentForm' => [...], 'upcomingMatches' => [...]]

getHeadToHead(string $team1, string $team2): array

Historical head-to-head match results between two teams.

$h2h = $client->getHeadToHead('Bayern München', 'Borussia Dortmund');
// [['date' => '2026-02-15', 'result' => '2:1', 'winner' => 'Bayern München', ...], ...]

Matches

getMatches(?string $season, ?string $fromDate, ?string $toDate, ?int $limit, ?int $offset): array

Paginated match history. All parameters are optional.

$matches = $client->getMatches(season: '2024/2025', limit: 50);
// [['homeTeam' => 'Bayern München', 'awayTeam' => 'BVB', 'homeElo' => 1835, ...], ...]

getUpcomingMatches(?string $league, ?string $sort, ?int $limit): array

Upcoming fixtures with ELO-difference predictions.

$upcoming = $client->getUpcomingMatches(league: 'BL1', limit: 20);
// [['homeTeam' => '...', 'awayTeam' => '...', 'eloDiff' => 40, ...], ...]

getMatch(int|string $matchId): array

Full detail for a single match.

$match = $client->getMatch(12345);
// ['match' => [...], 'homeRecentForm' => [...], 'awayRecentForm' => [...], ...]

Seasons

getSeasons(): array

List all available seasons and the most recent one.

$data = $client->getSeasons();
// ['seasons' => ['2025/2026', '2024/2025', ...], 'latestSeason' => '2025/2026']

getSeason(string $season, ?string $league): array

Per-team ELO change statistics for a given season.

$entries = $client->getSeason('2024/2025', league: 'BL1');
// [['teamName' => 'Bayern München', 'startElo' => 1820, 'endElo' => 1847, 'change' => 27, ...], ...]

Comparison

getComparisonHistory(array $teams): array

Time-series ELO data for multiple teams in one call. $teams must contain at least two names.

$history = $client->getComparisonHistory(['Bayern München', 'Borussia Dortmund']);
// [
//   'Bayern München'    => [['Date' => 1709856000000, 'ELO' => 1847], ...],
//   'Borussia Dortmund' => [['Date' => 1709856000000, 'ELO' => 1720], ...],
// ]

Error handling

All exceptions extend \ElevenElo\Exception\ElevenEloException.

use ElevenElo\Client;
use ElevenElo\Exception\AuthenticationException;
use ElevenElo\Exception\NotFoundException;
use ElevenElo\Exception\RateLimitException;

$client = new Client('11e_fre_your_key_here');

try {
    $team = $client->getTeam('Unknown FC');
} catch (NotFoundException $e) {
    echo 'Team not found' . PHP_EOL;
} catch (RateLimitException $e) {
    echo 'Rate limit hit, resets at ' . $e->resetAt . PHP_EOL;
} catch (AuthenticationException $e) {
    echo 'Bad API key' . PHP_EOL;
}

License

MIT