FOOTBALL API
Sign inRequest a key
The collectionDocumentationMembershipStatusSupport
Sign inRequest a key
Documentation / Seasons

FOOTBALL LEAGUE POSITIONS API

Positions
Complimentary key

Where every club stood in the table before each of its matches in a season. On the complimentary key it reads this season's Premier League.

GET/v1/competitions/{competition}/seasons/{season}/positions
TRY ITComplimentary
Kept in this browser for every docs page. No key yet? Get a free key
GET https://api.footballapi.org/v1/competitions/premier-league/seasons/2026/positions
The answer appears below, with its status and time.
curl "https://api.footballapi.org/v1/competitions/premier-league/seasons/2026/positions" \
  -H "X-API-Key: your key"

PARAMETERS

competitionrequiredstringA competition from /v1/competitions, such as premier-league. In the path.
seasonrequiredintegerThe first year of the season: 2026 for 2026/27. In the path.From 2015, or the competition's first season

RETURNS

match_idstringOur id for the match, mt_ and 9 characters, the same in every answer and for good
kickoff_utcstringKickoff in UTC, ISO 8601
kickoff_datestringThe day of kickoff in UTC, YYYY-MM-DD
homeobjectThe home side
home.club_idstringOur id for the club, cl_ and 9 characters, the same in every answer and for good
home.club_namestringThe club
home.positionintegerPlace in the table
awayobjectThe away side
away.club_idstringOur id for the club, cl_ and 9 characters, the same in every answer and for good
away.club_namestringThe club
away.positionintegerPlace in the table
full_time_resultstringhome, away or draw, at full time
position_gapintegerPlaces between the two clubs in the table at kickoff; below 0 when the away side stood higher

EXAMPLE ANSWER

200GET /v1/competitions/premier-league/seasons/2026/positions, taken 21 Oct 2026, first rows shown
{
  "data": [
    {
      "match_id": "mt_e2hk79mn5",
      "kickoff_utc": "2026-08-28T19:00:00Z",
      "kickoff_date": "2026-08-28",
      "home": {
        "club_id": "cl_aydtq01vq",
        "club_name": "Crystal Palace",
        "position": 16
      },
      "away": {
        "club_id": "cl_a7vhnxhhh",
        "club_name": "Manchester City",
        "position": 8
      },
      "full_time_result": "away",
      "position_gap": -8
    },
    {
      "match_id": "mt_9hm3yz9rt",
      "kickoff_utc": "2026-08-29T11:30:00Z",
      "kickoff_date": "2026-08-29",
      "home": {
        "club_id": "cl_0s0a8kn8x",
        "club_name": "Liverpool",
        "position": 10
      },
      "away": {
        "club_id": "cl_5bvjqjxyw",
        "club_name": "Nottingham Forest",
        "position": 15
      },
      "full_time_result": "draw",
      "position_gap": 5
    }
  ],
  "meta": {
    "competition": "premier-league",
    "season": "2026/27",
    "request_id": "req_7da802c65dfdf7ed"
  }
}

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.
PREVIOUSTableNEXTSeason clubs