FOOTBALL LEAGUE POSITION STATISTICS API

Positions and results

Complimentary key

How the gap between two clubs in the table at kickoff tracks the result, by competition and season. On the complimentary key it reads this season's Premier League.

GET/v1/stats/positions

TRY ITComplimentary

X-API-Key

Kept in this browser for every docs page. No key yet? Get a free key

competition

season

group_by

GET https://api.footballapi.org/v1/stats/positions?competition=premier-league&group_by=season

The answer appears below, with its status and time.

curl "https://api.footballapi.org/v1/stats/positions?competition=premier-league&group_by=season" \
  -H "X-API-Key: your key"

PARAMETERS

competitionstringA competition from /v1/competitions, such as premier-league. Leave it out for every competition your key reads.

seasonintegerThe first year of the season: 2026 for 2026/27.From 2015, or the competition's first season

group_bystringHow the figures are split: by competition, season, country, or competition and season.competition or season or country or competition_season

RETURNS

position_gapintegerPlaces between the two clubs in the table at kickoff; below 0 when the away side stood higher

meaningstringWhat the gap means, in words

matchesintegerMatches counted

goals_per_gamenumberGoals scored a match, on average

home_win_pctnumberShare of matches the home side won, as a percentage

draw_pctnumberShare of matches drawn, as a percentage

away_win_pctnumberShare of matches the away side won, as a percentage

EXAMPLE ANSWER

200GET /v1/stats/positions?competition=premier-league&group_by=season, taken 21 Oct 2026, first rows shown

{
  "data": [
    {
      "position_gap": -15,
      "meaning": "away side 15+ places higher",
      "matches": 514,
      "goals_per_game": 2.844,
      "home_win_pct": 19.65,
      "draw_pct": 21.6,
      "away_win_pct": 58.75
    },
    {
      "position_gap": -12,
      "meaning": "away side 12+ places higher",
      "matches": 749,
      "goals_per_game": 2.738,
      "home_win_pct": 28.04,
      "draw_pct": 23.9,
      "away_win_pct": 48.06
    }
  ],
  "meta": {
    "count": 11,
    "group_by": "season",
    "request_id": "req_b3dcdfbe499f39cb"
  }
}

ERRORS

401unauthorizedNo key, or a key we do not know.

400bad_requestA parameter is missing or not in the right form; the message names it.

403upgrade_requiredAnything outside this season's Premier League, on the complimentary key.

404not_foundAn id or competition we do not have.

422unknown_parameterA parameter this endpoint does not take.

429quota_exceededThe day's 50 calls are used, on the complimentary key; they reset at 00:00 UTC.

PREVIOUSReferee stats NEXTUsage