Football API documentation

Name: PlayerElo Football Ratings
Creator: PlayerElo
License: https://creativecommons.org/licenses/by/4.0/

Copy-paste examples for the PlayerElo football API — player & coach Elo ratings, match predictions, history and ESB betting tips. Grab a free key on the API overview (500 requests/month, no card), then run any request below.

Basics

Base URL — https://data-api.playerelo.football
Auth — every request needs an Authorization: Bearer YOUR_API_KEY header.
Format — JSON over HTTPS. List endpoints page with limit (max 100) and offset.
Errors — 401 (missing/invalid key), 404 (unknown id), 429 (rate limit / monthly quota).

GET/v1/players

List / search players

Players ranked by Elo (highest first). Pass search to resolve a name to an id.

Query params

search — case-insensitive name substring (optional)
limit — 1–100, default 20
offset — ≥ 0, default 0

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://data-api.playerelo.football/v1/players?search=Pedri&limit=1"

Example response

[
  {
    "player_id": "133609",
    "player_name": "Pedri",
    "elo": 2646.4,
    "position": "Midfielder",
    "current_team": "Barcelona",
    "current_league": "La Liga",
    "ear_label": "Elite"
  }
]

GET/v1/players/{id}

Get a player

A single player's full rating record — Elo, rank and (Elo Above Replacement) over the career, the last 12 months and the last 180 days.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://data-api.playerelo.football/v1/players/133609

Example response

{
  "player_id": "133609",
  "player_name": "Pedri",
  "player_type": "player",
  "elo": 2646.4,
  "position": "Midfielder",
  "position_group": "MID",
  "current_team": "Barcelona",
  "current_team_id": 529,
  "current_league": "La Liga",
  "current_league_id": 140,
  "current_rank": 1,
  "games_played": 317,
  "total_minutes": 25100,
  "ear_career": 49.8,
  "ear_label": "Elite",
  "ear_12m": 12.3,
  "ear_label_12m": "Elite",
  "ear_180": 5.0,
  "ear_label_180": "Elite"
}

GET/v1/players/{id}/history

Player rating history

Match-by-match Elo and (Elo Above Replacement over the prior 180 days), oldest first. ear may be null for older rows.

Query params

frm — inclusive start date YYYY-MM-DD (optional)
to — inclusive end date YYYY-MM-DD (optional)

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://data-api.playerelo.football/v1/players/133609/history

Example response

[
  { "date": "2019-08-17", "elo": 1512.0, "ear": null },
  { "date": "2026-05-18", "elo": 2646.4, "ear": 5.0 }
]

GET/v1/players/{id}/trend

28-day movement

Elo and rank change over the last 28 days. Positive rank_delta_28d means the player climbed.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://data-api.playerelo.football/v1/players/133609/trend

Example response

{
  "elo": 2646.4,
  "elo_prev_28d": 2641.2,
  "elo_delta_28d": 5.2,
  "current_rank": 1,
  "rank_prev_28d": 1,
  "rank_delta_28d": 0
}

GET/v1/coaches

List / search coaches

Coaches ranked by Elo. Coach ids are prefixed, e.g. coach_4.

Query params

search — name substring (optional)
limit — 1–100, default 20

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://data-api.playerelo.football/v1/coaches?limit=1"

Example response

[
  {
    "player_id": "coach_4",
    "player_name": "Pep Guardiola",
    "elo": 2512.5,
    "current_team": "Manchester City",
    "current_league": "Premier League",
    "ear_label": "Elite"
  }
]

GET/v1/fixtures

Upcoming fixtures, provisional predictions

Every fixture of the next two weeks, soonest kickoff first, with provisional home/draw/away probabilities from both squads' Elo (recalculated until kick-off; null while there are none yet). When lineup_prediction_available turns true, about 20 minutes before kick-off, /v1/fixtures/{id}/prediction has the lineup-based prediction. Without date: matches still to come or kicked off in the last 3 hours.

Query params

league — filter by league id (optional)
date — UTC kickoff date YYYY-MM-DD, past days included (optional)
limit — 1–100, default 20

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://data-api.playerelo.football/v1/fixtures?limit=1"

Example response

[
  {
    "fixture_id": 1234567,
    "kickoff_time": "2026-08-15T19:00:00+00:00",
    "league_id": 39,
    "league_name": "Premier League",
    "round": "Regular Season - 1",
    "status": "NS",
    "home_team_id": 42,
    "home_team": "Arsenal",
    "away_team_id": 49,
    "away_team": "Chelsea",
    "provisional": {
      "p_home": 0.46,
      "p_draw": 0.27,
      "p_away": 0.27,
      "home_team_elo": 1870.2,
      "away_team_elo": 1838.6,
      "computed_at": "2026-08-13T14:05:00+00:00"
    },
    "lineup_prediction_available": false
  }
]

GET/v1/predictions

Upcoming match predictions

Fixtures with confirmed lineups, soonest kickoff first, each with home/draw/away probabilities. A match appears once its line-ups are published, typically about 20 minutes before kick-off; for earlier, provisional probabilities use /v1/fixtures.

Query params

league — filter by league id (optional)
date — filter by kickoff date YYYY-MM-DD (optional)
limit — 1–100, default 20

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://data-api.playerelo.football/v1/predictions?limit=1"

Example response

[
  {
    "fixture_id": 1234567,
    "kickoff_time": "2026-08-15T19:00:00+00:00",
    "league_name": "Premier League",
    "league_id": 39,
    "home_team": "Arsenal",
    "away_team": "Chelsea",
    "home_team_elo": 1875.4,
    "away_team_elo": 1840.1,
    "p_home": 0.47,
    "p_draw": 0.26,
    "p_away": 0.27,
    "status": "NS"
  }
]

GET/v1/fixtures/{id}/prediction

Single fixture prediction

One fixture's probabilities plus a Monte-Carlo scoreline_distribution.

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://data-api.playerelo.football/v1/fixtures/1234567/prediction

Example response

{
  "fixture_id": 1234567,
  "home_team": "Arsenal",
  "away_team": "Chelsea",
  "home_team_elo": 1875.4,
  "away_team_elo": 1840.1,
  "p_home": 0.47,
  "p_draw": 0.26,
  "p_away": 0.27,
  "status": "NS",
  "scoreline_distribution": { "1-0": 0.11, "1-1": 0.10, "2-1": 0.09 }
}

GET/v1/value-bets

ESB betting tips

ESB (Established Squads Betting): our model's open bets before kick-off, plus the settled record (won/lost). Open bets appear in the last ~30 minutes before kick-off. On match days, check about every 15 minutes during the busy windows: weekdays 16:30–22:00, weekends 11:30–23:00, plus 23:30–05:30 for matches in the Americas (Central European time: UTC+2 in summer, UTC+1 in winter). In our measurement that catches about 80% of bets before kick-off for ~1,600 requests a month, which needs a paid plan; within the free plan's 500, weekday evenings (19:30–22:00) and weekend afternoons (14:30–22:00) alone catch about half. fair_odds (= 1 / model_prob) is ours, not a bookmaker's price. No profit is promised; model_version is null on rows before 2026-06-21.

Query params

strategy — e.g. hs2_v6 (optional)
status — open / won / lost / void (optional); void = removed from the record by the 2026-10-09 audit (placed after kick-off or priced off the wrong match), pl 0, reason in void_reason
since — return only rows with id greater than this; a bet keeps its id when it settles

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://data-api.playerelo.football/v1/value-bets?status=open&limit=1"

Example response

[
  {
    "id": 8842,
    "fixture_id": 1234567,
    "kickoff_time": "2026-08-15T19:00:00+00:00",
    "league_name": "Premier League",
    "home_team": "Arsenal",
    "away_team": "Chelsea",
    "bet_on": "home",
    "bookmaker": "pinnacle",
    "model_prob": 0.47,
    "edge": 0.04,
    "strategy": "hs2_v6",
    "status": "open",
    "pl": null,
    "resolved_at": null,
    "identified_at": "2026-08-15T18:40:00+00:00",
    "model_version": "football_v8.3",
    "fair_odds": 2.13
  }
]

This is a curated subset. For the full endpoint list (clubs, leagues, styles, simulations, recruitment analytics) and pricing, see the API overview. There's also a zero-dependency Python client on GitHub.