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

FOOTBALL COMPETITION API

Competition
Complimentary key

A competition in the collection: the first and last season served, how many matches it holds, and whether your key reads it. Every key can call it.

GET/v1/competitions/{competition}
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
The answer appears below, with its status and time.
curl "https://api.footballapi.org/v1/competitions/premier-league" \
  -H "X-API-Key: your key"

PARAMETERS

competitionrequiredstringA competition from /v1/competitions, such as premier-league. In the path.

RETURNS

competitionstringThe competition's name in the collection, such as premier-league
namestringThe competition as people write it
sincestringThe first season served
first_seasonintegerThe first season served, by its first year
last_seasonintegerThe latest season, by its first year
matchesintegerMatches counted
groupsintegerHow many groups it is played in; 1 for a single league
your_key_readsbooleanWhether your key reads it

EXAMPLE ANSWER

200GET /v1/competitions/premier-league, taken 21 Oct 2026
{
  "data": {
    "competition": "premier-league",
    "name": "England's Premier League",
    "since": "2015/16",
    "first_season": 2015,
    "last_season": 2026,
    "matches": 14756,
    "groups": 1,
    "your_key_reads": true
  },
  "meta": {
    "request_id": "req_74110ca02ebcffec"
  }
}

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.
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.
PREVIOUSCompetitionsNEXTCountries