Documentation

Quickstart / API Reference / Libraries / Samples

Daniel Freitag - Daniel@football-data.org - Version 2.0 | June 31 | 2018

Changelog v1 to v2

  • Most apparently I introduced paid tiers and added lots of competitions and more in-depth data like squads, scorers, assists and so on. This data is only available through v2.
  • I added several Subresources and even renamed some existing Resources, namely:
    • a Season-Subresource to Competition to act like a catalogue for historical data.
    • an Area-Resource to be able to categorize competitions by continent / country.
    • a Person-(Sub)Resource to represent players, coaches, referees and so on... (thus: persons)
    • I renamed the `Fixture`-Resource to `Match`-Resource.
    • I renamed the `LeagueTable`-Subresource to `Standings`.
  • A friend of mine redesigned the frontend (hope you like it :-))
  • I removed the HAL-headers. They were convenient for browsing the API but however. Hardly anyone did make use of it.
  • I removed the X-Response-Control header.

Vocabulary

Technical wording

Main Resources are main building blocks of the API and most likely also appear as entities in clients' applications. Subresources on the other hand generally don’t make sense without the Main Resource they are based on. You can also think of that a Main Resource actually is composed of Subresources. However often there are good arguments to justify one or the other design to be right. Trying to offer a flexible API you will see some "things" appear as both. Last but not least there are Filters to narrow down result sets. A Filter always describes an attribute and it’s value must be passed in an adequate format, which is declared by a Data Type. I usually describe these Data types using a loose regex-dialect.

Domain wording

A Competition represents a football league (e.g. Premiere League) or a tournament (e.g. FA-Cup) or a combination of both (e.g. Champions League, having playoffs, a group stage and knock-out rounds). All Competitions can be accessed via a particular id or a human readable code. A Competition consists of Seasons, that hold a number of scheduled games named Matches. A certain number of Teams participate in one particular Season. Since v2 there's even more Resources: Persons appear in squads and lineups as Players and Coaches or in matches as Referees. See all Resources listed on the left and click for example responses and available filters.

I omitted to implement particular Rounds or Matchdays as hierarchical elements by purpose. They are implemented as attributes of a Match, because I think this is more intuitive and separation can be achieved by using Filters.

Resource design

URI’s, Resources and Subresources are all written lower case. Enums use uppercase so a status is IN_PLAY and not in_play. All resources are only accessible using their plural, thus a resource by default responds with the list representation. Adding an id to the endpoint gives access to one particular resource.

Resources are represented as JSON-objects. In list representations you typically find a node 'count' that shows the number of results.

Requesting a Resource

For a first glimpse you can use your webbrowser to browse the API. To make the responses human-readable, install a browser-plugin (mentioned on the the landing page) that beautifies JSON output, or better yet use Postman. You can also use curl or Powershell to easily fetch resources, depending on your platform.

To implement the API there are lots of libraries and plugins that ease implementing RESTful APIs. I personally can recommend HTTP Requests Library by Bud Bird for Groovy/Java and Guzzle for PHP. But most probably you already got your favorite REST library at hand.

Also have a look at the open-sourced football-data.org API-libraries, which offer high level functions, that directly map to API resources. These are available in PHP, Ruby, Python, Golang and Perl6 (though not ported yet to v2).

The API follows the Query-string composition standard. So if you want to use Filters read more about query definition on wikipedia.

Please implement smart requests and always try to think about a good tradeoff between payload and the number of requests. Please don’t write loops to crawl resources from id 0 to id 1000. Don’t pull (thus: poll) resources too often, they usually do not change within a second.

Request Headers

Header-Name Possible values Description

X-Auth-Token

[a-z1-9]+

Your authentication token

Response Headers

Examine the underneath HTTP response headers to debug responses that do not look like you expected.

Header-Name Example value Description

X-API-Version

v2

indicates the version you are using

X-Authenticated-Client

Jimbo Jones

Shows the detected API-client or 'anonymous'

X-RequestCounter-Reset

23

Defines the seconds left to reset your request counter.

X-Requests-Available-Minute

28

Shows the remaining requests before being blocked.

Resources

Competition

The list representation of this resource is the de-facto entry point to the API and returns all available competitions.

Calling one particular resource basically serves a catalogue to see what seasons are available for that competition. In most cases however, you will use the Subresources to retrieve data.

Competition.json

{
    "id": 2003,
    "area": {
        "id": 2163,
        "name": "Netherlands"
    },
    "name": "Eredivisie",
    "code": null,
    "plan": "TIER_ONE",
    "currentSeason": {
        "id": 4,
        "startDate": "2017-08-11T19:00:00Z",
        "endDate": "2018-05-20T16:45:00Z",
        "currentMatchday": 34
    },
    "seasons": [
        {
            "id": 4,
            "startDate": "2017-08-11T19:00:00Z",
            "endDate": "2018-05-20T16:45:00Z",
            "currentMatchday": 34
        }
    ],
    "lastUpdated": "2018-06-05T00:17:50Z"
}

            

Available filters:

  • competitions

Available Subresources:

  • Matches (shows all matches of that competition. Defaults to the current season; use ?season=YYYY to retrieve former seasons)

  • Teams (shows all teams of that competition. Defaults to the current season by default; use ?season=YYYY to retrieve former seasons))

  • Standings (shows latest tables (total, home, away) for the current season; not yet available for former seasons)

  • Scorers (shows all goal scorers by shot goals descending for the current season)

Match

The Match resource reflects a scheduled football game. A match typically belongs to a competition and season and is played on a certain matchday.
In list representation, the Match Main Resource responds with all matches of the current day, whereas the Match Subresource of a Competition responds with all matches of the active season.

Match.json
{
    "head2head": {
        "numberOfMatches": 1,
        "totalGoals": 4,
        "homeTeam": {
            "wins": 1,
            "draws": 0,
            "losses": 0
        },
        "awayTeam": {
            "wins": 0,
            "draws": 0,
            "losses": 1
        }
    },
    "match": {
        "id": 200282,
        "competition": {
            "id": 2001,
            "name": "UEFA Champions League"
        },
        "season": {
            "id": 2,
            "startDate": "2017-06-27",
            "endDate": "2018-05-26",
            "currentMatchday": 6,
            "availableStages": [
                "1ST_QUALIFYING_ROUND",
                "2ND_QUALIFYING_ROUND",
                "3RD_QUALIFYING_ROUND",
                "PLAY_OFF_ROUND",
                "GROUP_STAGE",
                "ROUND_OF_16",
                "QUARTER_FINALS",
                "SEMI_FINALS",
                "FINAL"
            ]
        },
        "utcDate": "2018-05-26T18:45:00Z",
        "status": "FINISHED",
        "minute": null,
        "attendance": 61561,
        "venue": "NSK Olimpijs'kyj",
        "matchday": null,
        "stage": "FINAL",
        "group": "Final",
        "lastUpdated": "2018-06-22T10:00:12Z",
        "homeTeam": {
            "id": 86,
            "name": "Real Madrid CF",
            "coach": {
                "id": 79,
                "name": "Zinedine Zidane",
                "countryOfBirth": null,
                "nationality": null
            },
            "captain": {
                "id": 3192,
                "name": "Sergio Ramos",
                "shirtNumber": 4
            },
            "lineup": [
                {
                    "id": 43,
                    "name": "Luka Modrić",
                    "position": "Midfielder",
                    "shirtNumber": 10
                },
                {
                    "id": 44,
                    "name": "Cristiano Ronaldo",
                    "position": "Attacker",
                    "shirtNumber": 7
                },
                {
                    "id": 3192,
                    "name": "Sergio Ramos",
                    "position": "Defender",
                    "shirtNumber": 4
                },
                {
                    "id": 47,
                    "name": "Toni Kroos",
                    "position": "Midfielder",
                    "shirtNumber": 8
                },
                {
                    "id": 48,
                    "name": "Marcelo",
                    "position": "Defender",
                    "shirtNumber": 12
                },
                {
                    "id": 3194,
                    "name": "Dani Carvajal",
                    "position": "Defender",
                    "shirtNumber": 2
                },
                {
                    "id": 3360,
                    "name": "Raphaël Varane",
                    "position": "Defender",
                    "shirtNumber": 5
                },
                {
                    "id": 66,
                    "name": "Isco",
                    "position": "Midfielder",
                    "shirtNumber": 22
                },
                {
                    "id": 3231,
                    "name": "Casemiro",
                    "position": "Midfielder",
                    "shirtNumber": 14
                },
                {
                    "id": 49,
                    "name": "Karim Benzema",
                    "position": "Attacker",
                    "shirtNumber": 9
                },
                {
                    "id": 51,
                    "name": "Keylor Navas",
                    "position": "Goalkeeper",
                    "shirtNumber": 1
                }
            ],
            "bench": [
                {
                    "id": 3876,
                    "name": "Gareth Bale",
                    "position": "Midfielder",
                    "shirtNumber": 11
                },
                {
                    "id": 45,
                    "name": "Lucas Vázquez",
                    "position": "Midfielder",
                    "shirtNumber": 17
                },
                {
                    "id": 65,
                    "name": "Mateo Kovačić",
                    "position": "Midfielder",
                    "shirtNumber": 23
                },
                {
                    "id": 67,
                    "name": "Kiko Casilla",
                    "position": "Goalkeeper",
                    "shirtNumber": 13
                },
                {
                    "id": 50,
                    "name": "Nacho",
                    "position": "Defender",
                    "shirtNumber": 6
                },
                {
                    "id": 52,
                    "name": "Marco Asensio",
                    "position": "Midfielder",
                    "shirtNumber": 20
                },
                {
                    "id": 71,
                    "name": "Theo Hernández",
                    "position": "Defender",
                    "shirtNumber": 15
                }
            ]
        },
        "awayTeam": {
            "id": 64,
            "name": "Liverpool FC",
            "coach": {
                "id": 9344,
                "name": "Jürgen Klopp",
                "countryOfBirth": "Germany",
                "nationality": "Germany"
            },
            "captain": {
                "id": 3320,
                "name": "Jordan Henderson",
                "shirtNumber": 14
            },
            "lineup": [
                {
                    "id": 7861,
                    "name": "James Milner",
                    "position": "Defender",
                    "shirtNumber": 7
                },
                {
                    "id": 3320,
                    "name": "Jordan Henderson",
                    "position": "Midfielder",
                    "shirtNumber": 14
                },
                {
                    "id": 7859,
                    "name": "Dejan Lovren",
                    "position": "Defender",
                    "shirtNumber": 6
                },
                {
                    "id": 7868,
                    "name": "Andrew Robertson",
                    "position": "Defender",
                    "shirtNumber": 26
                },
                {
                    "id": 7871,
                    "name": "Georginio Wijnaldum",
                    "position": "Midfielder",
                    "shirtNumber": 5
                },
                {
                    "id": 3754,
                    "name": "Mohamed Salah",
                    "position": "Attacker",
                    "shirtNumber": 11
                },
                {
                    "id": 7856,
                    "name": "Loris Karius",
                    "position": "Goalkeeper",
                    "shirtNumber": 1
                },
                {
                    "id": 3233,
                    "name": "Roberto Firmino",
                    "position": "Midfielder",
                    "shirtNumber": 9
                },
                {
                    "id": 3626,
                    "name": "Sadio Mané",
                    "position": "Midfielder",
                    "shirtNumber": 19
                },
                {
                    "id": 7869,
                    "name": "Virgil van Dijk",
                    "position": "Defender",
                    "shirtNumber": 4
                },
                {
                    "id": 7867,
                    "name": "Trent Alexander-Arnold",
                    "position": "Defender",
                    "shirtNumber": 66
                }
            ],
            "bench": [
                {
                    "id": 3640,
                    "name": "Simon Mignolet",
                    "position": "Goalkeeper",
                    "shirtNumber": 22
                },
                {
                    "id": 3318,
                    "name": "Adam Lallana",
                    "position": "Midfielder",
                    "shirtNumber": 20
                },
                {
                    "id": 7863,
                    "name": "Nathaniel Clyne",
                    "position": "Defender",
                    "shirtNumber": 2
                },
                {
                    "id": 3183,
                    "name": "Emre Can",
                    "position": "Midfielder",
                    "shirtNumber": 23
                },
                {
                    "id": 7860,
                    "name": "Alberto Moreno",
                    "position": "Defender",
                    "shirtNumber": 18
                },
                {
                    "id": 7866,
                    "name": "Ragnar Klavan",
                    "position": "Defender",
                    "shirtNumber": 17
                },
                {
                    "id": 7878,
                    "name": "Dominic Solanke",
                    "position": "Attacker",
                    "shirtNumber": 29
                }
            ]
        },
        "score": {
            "winner": "HOME_TEAM",
            "duration": "REGULAR",
            "fullTime": {
                "homeTeam": 3,
                "awayTeam": 1
            },
            "halfTime": {
                "homeTeam": 0,
                "awayTeam": 0
            },
            "extraTime": {
                "homeTeam": null,
                "awayTeam": null
            },
            "penalties": {
                "homeTeam": null,
                "awayTeam": null
            }
        },
        "goals": [
            {
                "minute": 51,
                "extraTime": null,
                "type": "REGULAR",
                "team": {
                    "id": 86,
                    "name": "Real Madrid CF"
                },
                "scorer": {
                    "id": 49,
                    "name": "Karim Benzema"
                },
                "assist": null
            },
            {
                "minute": 55,
                "extraTime": null,
                "type": "REGULAR",
                "team": {
                    "id": 64,
                    "name": "Liverpool FC"
                },
                "scorer": {
                    "id": 3626,
                    "name": "Sadio Mané"
                },
                "assist": {
                    "id": 7859,
                    "name": "Dejan Lovren"
                }
            },
            {
                "minute": 64,
                "extraTime": null,
                "type": "REGULAR",
                "team": {
                    "id": 86,
                    "name": "Real Madrid CF"
                },
                "scorer": {
                    "id": 3876,
                    "name": "Gareth Bale"
                },
                "assist": {
                    "id": 48,
                    "name": "Marcelo"
                }
            },
            {
                "minute": 83,
                "extraTime": null,
                "type": "REGULAR",
                "team": {
                    "id": 86,
                    "name": "Real Madrid CF"
                },
                "scorer": {
                    "id": 3876,
                    "name": "Gareth Bale"
                },
                "assist": {
                    "id": 48,
                    "name": "Marcelo"
                }
            }
        ],
        "bookings": [
            {
                "minute": 82,
                "team": {
                    "id": 64,
                    "name": "Liverpool FC"
                },
                "player": {
                    "id": 3626,
                    "name": "Sadio Mané"
                },
                "card": "YELLOW_CARD"
            }
        ],
        "substitutions": [
            {
                "minute": 30,
                "team": {
                    "id": 64,
                    "name": "Liverpool FC"
                },
                "playerOut": {
                    "id": 3754,
                    "name": "Mohamed Salah"
                },
                "playerIn": {
                    "id": 3318,
                    "name": "Adam Lallana"
                }
            },
            {
                "minute": 37,
                "team": {
                    "id": 86,
                    "name": "Real Madrid CF"
                },
                "playerOut": {
                    "id": 3194,
                    "name": "Dani Carvajal"
                },
                "playerIn": {
                    "id": 50,
                    "name": "Nacho"
                }
            },
            {
                "minute": 61,
                "team": {
                    "id": 86,
                    "name": "Real Madrid CF"
                },
                "playerOut": {
                    "id": 66,
                    "name": "Isco"
                },
                "playerIn": {
                    "id": 3876,
                    "name": "Gareth Bale"
                }
            },
            {
                "minute": 83,
                "team": {
                    "id": 64,
                    "name": "Liverpool FC"
                },
                "playerOut": {
                    "id": 7861,
                    "name": "James Milner"
                },
                "playerIn": {
                    "id": 3183,
                    "name": "Emre Can"
                }
            },
            {
                "minute": 89,
                "team": {
                    "id": 86,
                    "name": "Real Madrid CF"
                },
                "playerOut": {
                    "id": 49,
                    "name": "Karim Benzema"
                },
                "playerIn": {
                    "id": 52,
                    "name": "Marco Asensio"
                }
            }
        ],
        "referees": [
            {
                "id": 9371,
                "name": "Milorad Mažić",
                "nationality": null
            },
            {
                "id": 9372,
                "name": "Milovan Ristić",
                "nationality": null
            },
            {
                "id": 9373,
                "name": "Dalibor Djurdjević",
                "nationality": null
            },
            {
                "id": 9374,
                "name": "Clément Turpin",
                "nationality": null
            },
            {
                "id": 9375,
                "name": "Nenad Djokic",
                "nationality": null
            },
            {
                "id": 9376,
                "name": "Danilo Grujić",
                "nationality": null
            },
            {
                "id": 56231,
                "name": "Dalibor Đurđević",
                "nationality": null
            }
        ]
    }
}

Available filters:

  • competitions

  • status

  • stage

  • group

  • dateFrom + dateTo

Last but not least see the underneath state diagram for possible values of the STATUS field.

State-Diagram
Figure 1. Possible values of the STATUS field.

Team

The Team resource gives access to all team details including squad and staff.

Team.json

{
    "id": 18,
    "area": {
        "id": 2088,
        "name": "Germany"
    },
    "name": "Borussia Mönchengladbach",
    "shortName": "M'gladbach",
    "tla": "BMG",
    "address": "Hennes-Weisweiler-Allee 1 Mönchengladbach 41179",
    "phone": "+49 (02161) 92930",
    "website": "http://www.borussia.de",
    "email": "info@borussia.de",
    "founded": 1900,
    "clubColors": "Black / White / Green",
    "venue": null,
    "squad": [
        {
            "id": 3176,
            "name": "Matthias Ginter",
            "position": "Defender",
            "dateOfBirth": "1994-01-03T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        { ... one more player ... },
        { ... one more player ... },
        { ... even more players ... }
    ],
    "lastUpdated": "2018-05-31T12:49:47Z"
}

            

Standings

Standings.json

{
    "season": {
        "id": 4,
        "startDate": "2017-08-11T19:00:00Z",
        "endDate": "2018-05-20T16:45:00Z",
        "currentMatchday": 34
    },
    "filters": {},
    "standings": [
        {
            "stage": "REGULAR_SEASON",
            "type": "TOTAL",
            "group": null,
            "table": [
                {
                    "position": 1,
                    "team": {
                        "id": 674,
                        "name": "PSV",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 26,
                    "draw": 5,
                    "lost": 3,
                    "points": 83,
                    "goalsFor": 87,
                    "goalsAgainst": 39,
                    "goalDifference": 48
                },
                {
                    "position": 2,
                    "team": {
                        "id": 678,
                        "name": "AFC Ajax",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 25,
                    "draw": 4,
                    "lost": 5,
                    "points": 79,
                    "goalsFor": 89,
                    "goalsAgainst": 33,
                    "goalDifference": 56
                },
                {
                    "position": 3,
                    "team": {
                        "id": 682,
                        "name": "AZ",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 22,
                    "draw": 5,
                    "lost": 7,
                    "points": 71,
                    "goalsFor": 72,
                    "goalsAgainst": 38,
                    "goalDifference": 34
                },
                { ... another rank ... },
            ]
        },
        {
            "stage": "REGULAR_SEASON",
            "type": "HOME",
            "group": null,
            "table": [
                {
                    "position": 1,
                    "team": {
                        "id": 674,
                        "name": "PSV",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 15,
                    "draw": 2,
                    "lost": 0,
                    "points": 47,
                    "goalsFor": 44,
                    "goalsAgainst": 9,
                    "goalDifference": 35
                },
                { ... another rank ... }
            ]
        },
        {
            "stage": "REGULAR_SEASON",
            "type": "AWAY",
            "group": null,
            "table": [
                {
                    "position": 1,
                    "team": {
                        "id": 678,
                        "name": "AFC Ajax",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 11,
                    "draw": 3,
                    "lost": 3,
                    "points": 36,
                    "goalsFor": 44,
                    "goalsAgainst": 21,
                    "goalDifference": 23
                },
                { ... another rank ... }                
            ]
        }
    ]
}

Available filters: None

Players

Player.json
{
    "id": 44,
    "name": "Cristiano Ronaldo",
    "firstName": "Cristiano Ronaldo",
    "lastName": null,
    "dateOfBirth": "1985-02-05",
    "countryOfBirth": "Portugal",
    "nationality": "Portugal",
    "position": "Attacker",
    "lastUpdated": "2018-08-09T05:07:03Z"
}

Available filters:

  • -

Available Subresources:

  • Matches (shows all matches of that player in all active competitions)

Filters

Filter Possible value(s) Description

id

Integer /[0-9]+/

The (unique) id of a resource.

matchday

Integer /[1-4]*[0-9]*/

For completed seasons the last matchday is taken. For the match resource, it’s unset.

status

Enum: [SCHEDULED | LIVE | IN_PLAY | PAUSED | FINISHED | POSTPONED | SUSPENDED | CANCELED]

Define the venue of the matches to be returned.

venue

Enum: [HOME|AWAY]

Define the venue of the matches to be returned.

dateFrom

\d\d\d\d-\d\d\-\d\d

The start date of the resources to be returned, e.g. 2016-08-01

dateTo

\d\d\d\d-\d\d\-\d\d

The end date of the resources to be returned, e.g. 2016-08-08

stage

String /[A-Z]+/

Check the season node for available stages of a particular competition/season.

season

\d\d\d\d-\d\d\-\d\d

Takes the (starting) year of a season as argument, e.g. 2017

plan

The backend representation of the pricing plans, e.g. TIER_ONE

limit

Limit your result set, e.g. 15

API Design

Request-Throttling

To protect the API from unnecessary load it is rate limited. Non-authenticated clients are allowed for 100 requests per 24 hours and can only access the area and competition list resources.
Registered clients are allowed for 10 requests/minute in the free plan and 30 requests/minute in all other plans. If the limit is not enough for your use-case, it's possible to increase it further.

Attributes and values

The API embraces null as a valid value, meaning all attributes can be null. The most obvious examples are values that are not known yet (the score of a game before it has ended, for instance).
Empty lists are valid as well. The important point here is, that attributes are there or not, but they won't be there sometimes and sometimes not within one resource.
Notice however, that I use different representations if I embed resources into list resources. Again here I don't think every information is useful in every resource which is why I often limit embedded objects to a subset of their attributes.

Season and matchday

The API always defaults to now, which basically is reflected by using an active season and a current matchday to pre-filter responses.

Active season
An active season is determined by it's start and end-date. In case the start date is no more than 30 days in the future and the end date is not more than 30 days in the past, a season is considered to be active. That means that if you e.g. request the matches subresource of a team, it will include all upcoming matches of a new season 30 days before it actually starts (premise is, that all matches are scheduled at this point). All matches of that season will vanish as soon as the last match is 30 days in the past.
Current matchday
The current matchday is determined by the following algorithm: from now (as of the time it is run every 3 hours), take the last and the next match of the season.
If their matchday is equal set the matchday to that matchday. If the gap between now and the next match is less that 36 hours or the gap between the last game and now is more than 60 hours, set the matchday to the matchday of the next game.

CORS handling

CORS (Cross-Origin-Resource-Sharing) is a mechanism that allows browsers to not load malicious code from a different servers than the original page was served from. There is an excellent article on SpringSource explaining CORS,^ so there’s no need to describe that further at this point. However, if you implement requests directly from Javascript, you need to add your X-Auth-Token correctly so the API gives you permission to do so. The basic workflow is as follows:

Before your Ajax request takes place your browser will automatically fire something like that:

OPTIONS http://api.football-data.org/v1/competitions/355/leagueTable

So that is your intentionally implemented request but not fired with GET but with the OPTIONS method. The API will respond with

204 No Content

response indicating there is no message body but also return the headers that are allowed. It reads as follows:

Access-Control-Allow-Methods "GET";
Access-Control-Allow-Origin "*";
Access-Control-Allow-Headers "x-auth-token, x-response-control";
Content-Length 0;
Content-Type text/plain;

Your browser now interprets this as "I am allowed to make that intended request" and fires the same request again with the GET method resulting in your desired response.

Errors

If something goes wrong you will likely face one of the following HTTP error codes. If the error is caused by the client the API will try to give you a hint with a small JSON encoded error message that looks like this:

{"error": "Parameter 'id' is expected to be an integer in a specific range."}

HTTP error codes returned

400 Bad Request Your request was malformed. Most likely the value of a Filter was not set according to the Data Type that is expected.
403 Restricted Resource You tried to access a resource that exists, but is not available to you. This can be due to the following reasons:
  • the resource is only available to authenticated clients.

  • the resource is only available to clients with a paid subscription.

  • the resource is not available in the API version you are using.

404 Not Found You tried to access a resource that doesn't exist
429 Too Many Requests You exceeded your API request quota. See Request-Throttling for more information.

Appendix

Table of League-Codes

Table 1. League-Codes used in the Competition resource
League-Code Country League
BL1 Germany 1. Bundesliga
BL2 Germany 2. Bundesliga
BL3 Germany 3. Bundesliga
DFB Germany Dfb-Cup
PL England Premiere League
EL1 England League One
ELC England Championship
FAC England FA-Cup
SA Italy Serie A
SB Italy Serie B
PD Spain Primera Division
SD Spain Segunda Division
CDR Spain Copa del Rey
FL1 France Ligue 1
FL2 France Ligue 2
DED Netherlands Eredivisie
PPL Portugal Primeira Liga
GSL Greece Super League
CL Europe Champions-League
EL Europe UEFA-Cup
EC Europe European-Cup of Nations
WC World World-Cup