Documentation

Quickstart / API Reference / Libraries

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 wget, 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-RequestsAvailable-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. In most cases however, you will use the Subresources to retrieve data.

Competition.json
copy

{
    "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: None

Available Subresources:

  • Matches (shows all matches of the current season by default)

  • Teams (shows all participating teams for the current season by default)

  • Standings (shows latest tables (total, home, away) 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. Match appears as Main Resource and as Subresource of a Competition/Season.

Match.json
copy

{
    "id": 200033,
    "competition": {
        "id": 2000,
        "name": "FIFA World Cup"
    },
    "season": {
        "id": 1,
        "startDate": "2018-06-14T17:00:00Z",
        "endDate": "2018-07-15T17:00:00Z",
        "currentMatchday": 3,
        "availableStages": [
            "GROUP_STAGE"
        ]
    },
    "utcDate": "2018-06-23T18:00:00Z",
    "status": "FINISHED",
    "minute": null,
    "attendance": 44287,
    "matchday": 2,
    "stage": "GROUP_STAGE",
    "group": "Group F",
    "lastUpdated": "2018-06-23T23:00:02Z",    
    "homeTeam": {
        "id": 759,
        "name": "Germany",
        "coach": {
            "id": 10178,
            "name": "Joachim Löw",
            "countryOfBirth": "Germany",
            "nationality": "Germany"
        },
        "captain": {
            "id": 341,
            "name": "Manuel Neuer",
            "shirtNumber": 1
        },
        "lineup": [
            {
                "id": 347,
                "name": "Jérôme Boateng",
                "position": "Defender",
                "shirtNumber": 17
            },
            {
                "id": 138,
                "name": "Marco Reus",
                "position": "Midfielder",
                "shirtNumber": 11
            },
            {
                "id": 3179,
                "name": "Julian Draxler",
                "position": "Midfielder",
                "shirtNumber": 7
            },
            {
                "id": 3177,
                "name": "Antonio Rüdiger",
                "position": "Defender",
                "shirtNumber": 16
            },
            {
                "id": 3187,
                "name": "Timo Werner",
                "position": "Attacker",
                "shirtNumber": 9
            },
            {
                "id": 341,
                "name": "Manuel Neuer",
                "position": "Goalkeeper",
                "shirtNumber": 1
            },
            {
                "id": 47,
                "name": "Toni Kroos",
                "position": "Midfielder",
                "shirtNumber": 8
            },
            {
                "id": 370,
                "name": "Thomas Müller",
                "position": "Attacker",
                "shirtNumber": 13
            },
            {
                "id": 367,
                "name": "Sebastian Rudy",
                "position": "Midfielder",
                "shirtNumber": 19
            },
            {
                "id": 184,
                "name": "Jonas Hector",
                "position": "Defender",
                "shirtNumber": 3
            },
            {
                "id": 359,
                "name": "Joshua Kimmich",
                "position": "Midfielder",
                "shirtNumber": 18
            }
        ],
        "bench": [
            {
                "id": 350,
                "name": "Mats Hummels",
                "position": "Defender",
                "shirtNumber": 5
            },
            {
                "id": 3181,
                "name": "Leon Goretzka",
                "position": "Midfielder",
                "shirtNumber": 14
            },
            {
                "id": 148,
                "name": "Julian Brandt",
                "position": "Attacker",
                "shirtNumber": 20
            },
            {
                "id": 3186,
                "name": "Mario Gómez",
                "position": "Attacker",
                "shirtNumber": 23
            },
            {
                "id": 3180,
                "name": "Mesut Özil",
                "position": "Midfielder",
                "shirtNumber": 10
            },
            {
                "id": 2035,
                "name": "Sami Khedira",
                "position": "Midfielder",
                "shirtNumber": 6
            },
            {
                "id": 3176,
                "name": "Matthias Ginter",
                "position": "Defender",
                "shirtNumber": 4
            },
            {
                "id": 3175,
                "name": "Kevin Trapp",
                "position": "Goalkeeper",
                "shirtNumber": 12
            },
            {
                "id": 351,
                "name": "Niklas Süle",
                "position": "Defender",
                "shirtNumber": 15
            },
            {
                "id": 3173,
                "name": "Marc-André ter Stegen",
                "position": "Goalkeeper",
                "shirtNumber": 22
            },
            {
                "id": 3178,
                "name": "Marvin Plattenhardt",
                "position": "Defender",
                "shirtNumber": 2
            },
            {
                "id": 3182,
                "name": "Ilkay Gündogan",
                "position": "Midfielder",
                "shirtNumber": 21
            }
        ]
    },
    "awayTeam": {
        "id": 792,
        "name": "Sweden",
        "coach": {
            "id": 10198,
            "name": "Janne Andersson",
            "countryOfBirth": "Sweden",
            "nationality": "Sweden"
        },
        "captain": {
            "id": 3488,
            "name": "Andreas Granqvist",
            "shirtNumber": 4
        },
        "lineup": [
            {
                "id": 3488,
                "name": "Andreas Granqvist",
                "position": "Defender",
                "shirtNumber": 4
            },
            {
                "id": 3493,
                "name": "Sebastian Larsson",
                "position": "Midfielder",
                "shirtNumber": 7
            },
            {
                "id": 6527,
                "name": "Albin Ekdal",
                "position": "Midfielder",
                "shirtNumber": 8
            },
            {
                "id": 3502,
                "name": "Ola Toivonen",
                "position": "Attacker",
                "shirtNumber": 20
            },
            {
                "id": 3489,
                "name": "Mikael Lustig",
                "position": "Defender",
                "shirtNumber": 2
            },
            {
                "id": 3494,
                "name": "Emil Forsberg",
                "position": "Midfielder",
                "shirtNumber": 10
            },
            {
                "id": 15512,
                "name": "Robin Olsen",
                "position": "Goalkeeper",
                "shirtNumber": 1
            },
            {
                "id": 3499,
                "name": "Viktor Claesson",
                "position": "Midfielder",
                "shirtNumber": 17
            },
            {
                "id": 9445,
                "name": "Ludwig Augustinsson",
                "position": "Defender",
                "shirtNumber": 6
            },
            {
                "id": 3504,
                "name": "Marcus Berg",
                "position": "Attacker",
                "shirtNumber": 9
            },
            {
                "id": 3492,
                "name": "Victor Nilsson-Lindelöf",
                "position": "Defender",
                "shirtNumber": 3
            }
        ],
        "bench": [
            {
                "id": 3487,
                "name": "Martin Olsson",
                "position": "Defender",
                "shirtNumber": 5
            },
            {
                "id": 3501,
                "name": "John Guidetti",
                "position": "Attacker",
                "shirtNumber": 11
            },
            {
                "id": 3490,
                "name": "Pontus Jansson",
                "position": "Defender",
                "shirtNumber": 18
            },
            {
                "id": 1871,
                "name": "Filip Helander",
                "position": "Defender",
                "shirtNumber": 14
            },
            {
                "id": 3503,
                "name": "Isaac Thelin",
                "position": "Attacker",
                "shirtNumber": 22
            },
            {
                "id": 2222,
                "name": "Marcus Rohdén",
                "position": "Midfielder",
                "shirtNumber": 19
            },
            {
                "id": 1868,
                "name": "Emil Krafth",
                "position": "Defender",
                "shirtNumber": 16
            },
            {
                "id": 3497,
                "name": "Gustav Svensson",
                "position": "Midfielder",
                "shirtNumber": 13
            },
            {
                "id": 3485,
                "name": "Karl-Johan Johnsson",
                "position": "Goalkeeper",
                "shirtNumber": 12
            },
            {
                "id": 3495,
                "name": "Jimmy Durmaz",
                "position": "Midfielder",
                "shirtNumber": 21
            },
            {
                "id": 3484,
                "name": "Kristoffer Nordfeldt",
                "position": "Goalkeeper",
                "shirtNumber": 23
            },
            {
                "id": 1984,
                "name": "Oscar Hiljemark",
                "position": "Midfielder",
                "shirtNumber": 15
            }
        ]
    },
    "score": {
        "winner": "HOME_TEAM",
        "duration": "REGULAR",
        "halfTime": {
            "homeTeam": 0,
            "awayTeam": 1
        },
        "fullTime": {
            "homeTeam": 2,
            "awayTeam": 1
        },
        "extraTime": {
            "homeTeam": null,
            "awayTeam": null
        },
        "penalties": {
            "homeTeam": null,
            "awayTeam": null
        }
    },
    "goals": [
        {
            "minute": 32,
            "scorer": {
                "id": 3502,
                "name": "Ola Toivonen"
            },
            "assist": [
                {
                    "id": 3499,
                    "name": "Viktor Claesson"
                }
            ]
        },
        {
            "minute": 48,
            "scorer": {
                "id": 138,
                "name": "Marco Reus"
            },
            "assist": [
                {
                    "id": 3186,
                    "name": "Mario Gómez"
                }
            ]
        },
        {
            "minute": 90,
            "scorer": {
                "id": 47,
                "name": "Toni Kroos"
            },
            "assist": [
                {
                    "id": 138,
                    "name": "Marco Reus"
                }
            ]
        }
    ],
    "bookings": [
        {
            "minute": 52,
            "team": {
                "id": 792,
                "name": "Sweden"
            },
            "player": {
                "id": 6527,
                "name": "Albin Ekdal"
            },
            "card": "YELLOW_CARD"
        },
        {
            "minute": 71,
            "team": {
                "id": 759,
                "name": "Germany"
            },
            "player": {
                "id": 347,
                "name": "Jérôme Boateng"
            },
            "card": "YELLOW_CARD"
        },
        {
            "minute": 82,
            "team": {
                "id": 759,
                "name": "Germany"
            },
            "player": {
                "id": 347,
                "name": "Jérôme Boateng"
            },
            "card": "YELLOW_RED_CARD"
        },
        {
            "minute": 90,
            "team": {
                "id": 792,
                "name": "Sweden"
            },
            "player": {
                "id": 3493,
                "name": "Sebastian Larsson"
            },
            "card": "YELLOW_CARD"
        }
    ],
    "substitutions": [
        {
            "minute": 31,
            "team": {
                "id": 759,
                "name": "Germany"
            },
            "playerOut": {
                "id": 367,
                "name": "Sebastian Rudy"
            },
            "playerIn": {
                "id": 3182,
                "name": "Ilkay Gündogan"
            }
        },
        {
            "minute": 46,
            "team": {
                "id": 759,
                "name": "Germany"
            },
            "playerOut": {
                "id": 3179,
                "name": "Julian Draxler"
            },
            "playerIn": {
                "id": 3186,
                "name": "Mario Gómez"
            }
        },
        {
            "minute": 74,
            "team": {
                "id": 792,
                "name": "Sweden"
            },
            "playerOut": {
                "id": 3499,
                "name": "Viktor Claesson"
            },
            "playerIn": {
                "id": 3495,
                "name": "Jimmy Durmaz"
            }
        },
        {
            "minute": 78,
            "team": {
                "id": 792,
                "name": "Sweden"
            },
            "playerOut": {
                "id": 3502,
                "name": "Ola Toivonen"
            },
            "playerIn": {
                "id": 3501,
                "name": "John Guidetti"
            }
        },
        {
            "minute": 87,
            "team": {
                "id": 759,
                "name": "Germany"
            },
            "playerOut": {
                "id": 184,
                "name": "Jonas Hector"
            },
            "playerIn": {
                "id": 148,
                "name": "Julian Brandt"
            }
        },
        {
            "minute": 90,
            "team": {
                "id": 792,
                "name": "Sweden"
            },
            "playerOut": {
                "id": 3504,
                "name": "Marcus Berg"
            },
            "playerIn": {
                "id": 3503,
                "name": "Isaac Thelin"
            }
        }
    ],
    "referees": [
        {
            "id": 43888,
            "name": "Szymon Marciniak",
            "nationality": null
        },
        {
            "id": 43889,
            "name": "Paweł Sokolnicki",
            "nationality": null
        },
        {
            "id": 43890,
            "name": "Tomasz Listkiewicz",
            "nationality": null
        },
        {
            "id": 49525,
            "name": "Ryūji Satō",
            "nationality": null
        },
        {
            "id": 55658,
            "name": "Toru Sagara",
            "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
copy

{
    "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"
        },
        {
            "id": 3185,
            "name": "Lars Stindl",
            "position": "Midfielder",
            "dateOfBirth": "1988-01-04T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 3470,
            "name": "Yann Sommer",
            "position": "Goalkeeper",
            "dateOfBirth": "1988-01-04T00:00:00Z",
            "countryOfBirth": "Switzerland",
            "nationality": "Switzerland",
            "role": "PLAYER"
        },
        {
            "id": 3475,
            "name": "Nico Elvedi",
            "position": "Defender",
            "dateOfBirth": "1996-01-01T00:00:00Z",
            "countryOfBirth": "Switzerland",
            "nationality": "Switzerland",
            "role": "PLAYER"
        },
        {
            "id": 3480,
            "name": "Josip Drmić",
            "position": "Attacker",
            "dateOfBirth": "1991-12-30T00:00:00Z",
            "countryOfBirth": "Switzerland",
            "nationality": "Switzerland",
            "role": "PLAYER"
        },
        {
            "id": 3655,
            "name": "Thorgan Hazard",
            "position": "Midfielder",
            "dateOfBirth": "1993-01-04T00:00:00Z",
            "countryOfBirth": "Belgium",
            "nationality": "Belgium",
            "role": "PLAYER"
        },
        {
            "id": 6666,
            "name": "Christofer Heimeroth",
            "position": "Goalkeeper",
            "dateOfBirth": "1980-12-29T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6667,
            "name": "Tobias Sippel",
            "position": "Goalkeeper",
            "dateOfBirth": "1988-01-04T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6668,
            "name": "Moritz Nicolas",
            "position": "Goalkeeper",
            "dateOfBirth": "1996-12-30T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6669,
            "name": "Oscar Wendt",
            "position": "Defender",
            "dateOfBirth": "1984-12-31T00:00:00Z",
            "countryOfBirth": "Sweden",
            "nationality": "Sweden",
            "role": "PLAYER"
        },
        {
            "id": 6670,
            "name": "Tony Jantschke",
            "position": "Defender",
            "dateOfBirth": "1990-01-01T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6671,
            "name": "Jannik Vestergaard",
            "position": "Defender",
            "dateOfBirth": "1991-12-30T00:00:00Z",
            "countryOfBirth": "Denmark",
            "nationality": "Denmark",
            "role": "PLAYER"
        },
        {
            "id": 6672,
            "name": "Mamadou Doucouré",
            "position": "Defender",
            "dateOfBirth": "1997-12-29T00:00:00Z",
            "countryOfBirth": "Senegal",
            "nationality": "France",
            "role": "PLAYER"
        },
        {
            "id": 6673,
            "name": "Justin Hoffmans",
            "position": "Defender",
            "dateOfBirth": "1996-12-30T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6674,
            "name": "Marcel Benger",
            "position": "Defender",
            "dateOfBirth": "1997-12-29T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6675,
            "name": "Florian Mayer",
            "position": "Defender",
            "dateOfBirth": "1997-12-29T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6676,
            "name": "Mandela Egbo",
            "position": "Defender",
            "dateOfBirth": "1996-12-30T00:00:00Z",
            "countryOfBirth": "England",
            "nationality": "England",
            "role": "PLAYER"
        },
        {
            "id": 6677,
            "name": "Reece Oxford",
            "position": "Defender",
            "dateOfBirth": "1997-12-29T00:00:00Z",
            "countryOfBirth": "England",
            "nationality": "England",
            "role": "PLAYER"
        },
        {
            "id": 6678,
            "name": "Louis Beyer",
            "position": "Defender",
            "dateOfBirth": "2000-01-03T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6679,
            "name": "Ibrahima Traoré",
            "position": "Midfielder",
            "dateOfBirth": "1988-01-04T00:00:00Z",
            "countryOfBirth": "France",
            "nationality": "Guinea",
            "role": "PLAYER"
        },
        {
            "id": 6680,
            "name": "Patrick Herrmann",
            "position": "Midfielder",
            "dateOfBirth": "1990-12-31T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6681,
            "name": "Jonas Hofmann",
            "position": "Midfielder",
            "dateOfBirth": "1991-12-30T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6682,
            "name": "Christoph Kramer",
            "position": "Midfielder",
            "dateOfBirth": "1990-12-31T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6683,
            "name": "Tobias Strobl",
            "position": "Midfielder",
            "dateOfBirth": "1990-01-01T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6684,
            "name": "László Bénes",
            "position": "Midfielder",
            "dateOfBirth": "1996-12-30T00:00:00Z",
            "countryOfBirth": "Slovakia",
            "nationality": "Slovakia",
            "role": "PLAYER"
        },
        {
            "id": 6685,
            "name": "Nils Rütten",
            "position": "Midfielder",
            "dateOfBirth": "1995-01-02T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6686,
            "name": "Vincenzo Grifo",
            "position": "Midfielder",
            "dateOfBirth": "1993-01-04T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6687,
            "name": "Denis Zakaria",
            "position": "Midfielder",
            "dateOfBirth": "1996-01-01T00:00:00Z",
            "countryOfBirth": "Congo DR",
            "nationality": "Switzerland",
            "role": "PLAYER"
        },
        {
            "id": 6688,
            "name": "Mickaël Cuisance",
            "position": "Midfielder",
            "dateOfBirth": "1999-01-04T00:00:00Z",
            "countryOfBirth": "France",
            "nationality": "France",
            "role": "PLAYER"
        },
        {
            "id": 6689,
            "name": "Aaron Herzog",
            "position": "Midfielder",
            "dateOfBirth": "1997-12-29T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6690,
            "name": "Fabian Johnson",
            "position": "Attacker",
            "dateOfBirth": "1986-12-29T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "United States",
            "role": "PLAYER"
        },
        {
            "id": 6691,
            "name": "Raffael",
            "position": "Attacker",
            "dateOfBirth": "1984-12-31T00:00:00Z",
            "countryOfBirth": "Brazil",
            "nationality": "Brazil",
            "role": "PLAYER"
        },
        {
            "id": 6692,
            "name": "Ba-Muaka Simakala",
            "position": "Attacker",
            "dateOfBirth": "1996-12-30T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Congo",
            "role": "PLAYER"
        },
        {
            "id": 6693,
            "name": "Mike Feigenspan",
            "position": "Attacker",
            "dateOfBirth": "1995-01-02T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "PLAYER"
        },
        {
            "id": 6694,
            "name": "Julio Villalba",
            "position": "Attacker",
            "dateOfBirth": "1997-12-29T00:00:00Z",
            "countryOfBirth": "Paraguay",
            "nationality": "Paraguay",
            "role": "PLAYER"
        },
        {
            "id": 6695,
            "name": "Raúl Bobadilla",
            "position": "Attacker",
            "dateOfBirth": "1986-12-29T00:00:00Z",
            "countryOfBirth": "Argentina",
            "nationality": "Paraguay",
            "role": "PLAYER"
        },
        {
            "id": 10244,
            "name": "Dieter Hecking",
            "position": null,
            "dateOfBirth": "1963-12-30T00:00:00Z",
            "countryOfBirth": "Germany",
            "nationality": "Germany",
            "role": "COACH"
        }
    ],
    "lastUpdated": "2018-05-31T12:49:47Z"
}

            

Standings

Standings.json
copy

{
    "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
                },
                {
                    "position": 4,
                    "team": {
                        "id": 675,
                        "name": "Feyenoord Rotterdam",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 20,
                    "draw": 6,
                    "lost": 8,
                    "points": 66,
                    "goalsFor": 76,
                    "goalsAgainst": 39,
                    "goalDifference": 37
                },
                {
                    "position": 5,
                    "team": {
                        "id": 676,
                        "name": "FC Utrecht",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 14,
                    "draw": 12,
                    "lost": 8,
                    "points": 54,
                    "goalsFor": 58,
                    "goalsAgainst": 53,
                    "goalDifference": 5
                },
                {
                    "position": 6,
                    "team": {
                        "id": 679,
                        "name": "SBV Vitesse",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 13,
                    "draw": 10,
                    "lost": 11,
                    "points": 49,
                    "goalsFor": 63,
                    "goalsAgainst": 47,
                    "goalDifference": 16
                },
                {
                    "position": 7,
                    "team": {
                        "id": 680,
                        "name": "ADO Den Haag",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 13,
                    "draw": 8,
                    "lost": 13,
                    "points": 47,
                    "goalsFor": 45,
                    "goalsAgainst": 53,
                    "goalDifference": -8
                },
                {
                    "position": 8,
                    "team": {
                        "id": 673,
                        "name": "SC Heerenveen",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 12,
                    "draw": 10,
                    "lost": 12,
                    "points": 46,
                    "goalsFor": 48,
                    "goalsAgainst": 53,
                    "goalDifference": -5
                },
                {
                    "position": 9,
                    "team": {
                        "id": 684,
                        "name": "PEC Zwolle",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 12,
                    "draw": 8,
                    "lost": 14,
                    "points": 44,
                    "goalsFor": 42,
                    "goalsAgainst": 54,
                    "goalDifference": -12
                },
                {
                    "position": 10,
                    "team": {
                        "id": 671,
                        "name": "Heracles Almelo",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 11,
                    "draw": 9,
                    "lost": 14,
                    "points": 42,
                    "goalsFor": 50,
                    "goalsAgainst": 64,
                    "goalDifference": -14
                },
                {
                    "position": 11,
                    "team": {
                        "id": 670,
                        "name": "SBV Excelsior",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 11,
                    "draw": 7,
                    "lost": 16,
                    "points": 40,
                    "goalsFor": 41,
                    "goalsAgainst": 56,
                    "goalDifference": -15
                },
                {
                    "position": 12,
                    "team": {
                        "id": 677,
                        "name": "FC Groningen",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 8,
                    "draw": 14,
                    "lost": 12,
                    "points": 38,
                    "goalsFor": 50,
                    "goalsAgainst": 50,
                    "goalDifference": 0
                },
                {
                    "position": 13,
                    "team": {
                        "id": 672,
                        "name": "Willem II Tilburg",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 10,
                    "draw": 7,
                    "lost": 17,
                    "points": 37,
                    "goalsFor": 50,
                    "goalsAgainst": 63,
                    "goalDifference": -13
                },
                {
                    "position": 14,
                    "team": {
                        "id": 681,
                        "name": "NAC Breda",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 9,
                    "draw": 7,
                    "lost": 18,
                    "points": 34,
                    "goalsFor": 41,
                    "goalsAgainst": 57,
                    "goalDifference": -16
                },
                {
                    "position": 15,
                    "team": {
                        "id": 668,
                        "name": "VVV Venlo",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 7,
                    "draw": 13,
                    "lost": 14,
                    "points": 34,
                    "goalsFor": 35,
                    "goalsAgainst": 54,
                    "goalDifference": -19
                },
                {
                    "position": 16,
                    "team": {
                        "id": 665,
                        "name": "SV Roda JC",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 8,
                    "draw": 6,
                    "lost": 20,
                    "points": 30,
                    "goalsFor": 42,
                    "goalsAgainst": 69,
                    "goalDifference": -27
                },
                {
                    "position": 17,
                    "team": {
                        "id": null,
                        "name": null,
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 7,
                    "draw": 6,
                    "lost": 21,
                    "points": 27,
                    "goalsFor": 34,
                    "goalsAgainst": 75,
                    "goalDifference": -41
                },
                {
                    "position": 18,
                    "team": {
                        "id": 666,
                        "name": "FC Twente '65",
                        "crestURI": null
                    },
                    "playedGames": 34,
                    "won": 5,
                    "draw": 9,
                    "lost": 20,
                    "points": 24,
                    "goalsFor": 37,
                    "goalsAgainst": 63,
                    "goalDifference": -26
                }
            ]
        },
        {
            "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
                },
                {
                    "position": 2,
                    "team": {
                        "id": 678,
                        "name": "AFC Ajax",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 14,
                    "draw": 1,
                    "lost": 2,
                    "points": 43,
                    "goalsFor": 45,
                    "goalsAgainst": 12,
                    "goalDifference": 33
                },
                {
                    "position": 3,
                    "team": {
                        "id": 675,
                        "name": "Feyenoord Rotterdam",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 11,
                    "draw": 3,
                    "lost": 3,
                    "points": 36,
                    "goalsFor": 37,
                    "goalsAgainst": 17,
                    "goalDifference": 20
                },
                {
                    "position": 4,
                    "team": {
                        "id": 682,
                        "name": "AZ",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 11,
                    "draw": 2,
                    "lost": 4,
                    "points": 35,
                    "goalsFor": 40,
                    "goalsAgainst": 23,
                    "goalDifference": 17
                },
                {
                    "position": 5,
                    "team": {
                        "id": 676,
                        "name": "FC Utrecht",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 9,
                    "draw": 7,
                    "lost": 1,
                    "points": 34,
                    "goalsFor": 32,
                    "goalsAgainst": 21,
                    "goalDifference": 11
                },
                {
                    "position": 6,
                    "team": {
                        "id": 671,
                        "name": "Heracles Almelo",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 9,
                    "draw": 4,
                    "lost": 4,
                    "points": 31,
                    "goalsFor": 29,
                    "goalsAgainst": 25,
                    "goalDifference": 4
                },
                {
                    "position": 7,
                    "team": {
                        "id": 677,
                        "name": "FC Groningen",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 7,
                    "draw": 7,
                    "lost": 3,
                    "points": 28,
                    "goalsFor": 32,
                    "goalsAgainst": 21,
                    "goalDifference": 11
                },
                {
                    "position": 8,
                    "team": {
                        "id": 684,
                        "name": "PEC Zwolle",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 8,
                    "draw": 4,
                    "lost": 5,
                    "points": 28,
                    "goalsFor": 27,
                    "goalsAgainst": 20,
                    "goalDifference": 7
                },
                {
                    "position": 9,
                    "team": {
                        "id": 679,
                        "name": "SBV Vitesse",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 7,
                    "draw": 6,
                    "lost": 4,
                    "points": 27,
                    "goalsFor": 35,
                    "goalsAgainst": 20,
                    "goalDifference": 15
                },
                {
                    "position": 10,
                    "team": {
                        "id": 680,
                        "name": "ADO Den Haag",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 7,
                    "draw": 4,
                    "lost": 6,
                    "points": 25,
                    "goalsFor": 26,
                    "goalsAgainst": 27,
                    "goalDifference": -1
                },
                {
                    "position": 11,
                    "team": {
                        "id": 673,
                        "name": "SC Heerenveen",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 6,
                    "draw": 5,
                    "lost": 6,
                    "points": 23,
                    "goalsFor": 21,
                    "goalsAgainst": 24,
                    "goalDifference": -3
                },
                {
                    "position": 12,
                    "team": {
                        "id": 672,
                        "name": "Willem II Tilburg",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 6,
                    "draw": 4,
                    "lost": 7,
                    "points": 22,
                    "goalsFor": 31,
                    "goalsAgainst": 29,
                    "goalDifference": 2
                },
                {
                    "position": 13,
                    "team": {
                        "id": 681,
                        "name": "NAC Breda",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 7,
                    "draw": 1,
                    "lost": 9,
                    "points": 22,
                    "goalsFor": 26,
                    "goalsAgainst": 31,
                    "goalDifference": -5
                },
                {
                    "position": 14,
                    "team": {
                        "id": null,
                        "name": null,
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 6,
                    "draw": 2,
                    "lost": 9,
                    "points": 20,
                    "goalsFor": 21,
                    "goalsAgainst": 36,
                    "goalDifference": -15
                },
                {
                    "position": 15,
                    "team": {
                        "id": 666,
                        "name": "FC Twente '65",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 4,
                    "draw": 6,
                    "lost": 7,
                    "points": 18,
                    "goalsFor": 25,
                    "goalsAgainst": 31,
                    "goalDifference": -6
                },
                {
                    "position": 16,
                    "team": {
                        "id": 665,
                        "name": "SV Roda JC",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 4,
                    "draw": 4,
                    "lost": 9,
                    "points": 16,
                    "goalsFor": 21,
                    "goalsAgainst": 34,
                    "goalDifference": -13
                },
                {
                    "position": 17,
                    "team": {
                        "id": 668,
                        "name": "VVV Venlo",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 3,
                    "draw": 6,
                    "lost": 8,
                    "points": 15,
                    "goalsFor": 19,
                    "goalsAgainst": 29,
                    "goalDifference": -10
                },
                {
                    "position": 18,
                    "team": {
                        "id": 670,
                        "name": "SBV Excelsior",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 3,
                    "draw": 5,
                    "lost": 9,
                    "points": 14,
                    "goalsFor": 16,
                    "goalsAgainst": 24,
                    "goalDifference": -8
                }
            ]
        },
        {
            "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
                },
                {
                    "position": 2,
                    "team": {
                        "id": 682,
                        "name": "AZ",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 11,
                    "draw": 3,
                    "lost": 3,
                    "points": 36,
                    "goalsFor": 32,
                    "goalsAgainst": 15,
                    "goalDifference": 17
                },
                {
                    "position": 3,
                    "team": {
                        "id": 674,
                        "name": "PSV",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 11,
                    "draw": 3,
                    "lost": 3,
                    "points": 36,
                    "goalsFor": 43,
                    "goalsAgainst": 30,
                    "goalDifference": 13
                },
                {
                    "position": 4,
                    "team": {
                        "id": 675,
                        "name": "Feyenoord Rotterdam",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 9,
                    "draw": 3,
                    "lost": 5,
                    "points": 30,
                    "goalsFor": 39,
                    "goalsAgainst": 22,
                    "goalDifference": 17
                },
                {
                    "position": 5,
                    "team": {
                        "id": 670,
                        "name": "SBV Excelsior",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 8,
                    "draw": 2,
                    "lost": 7,
                    "points": 26,
                    "goalsFor": 25,
                    "goalsAgainst": 32,
                    "goalDifference": -7
                },
                {
                    "position": 6,
                    "team": {
                        "id": 673,
                        "name": "SC Heerenveen",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 6,
                    "draw": 5,
                    "lost": 6,
                    "points": 23,
                    "goalsFor": 27,
                    "goalsAgainst": 29,
                    "goalDifference": -2
                },
                {
                    "position": 7,
                    "team": {
                        "id": 679,
                        "name": "SBV Vitesse",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 6,
                    "draw": 4,
                    "lost": 7,
                    "points": 22,
                    "goalsFor": 28,
                    "goalsAgainst": 27,
                    "goalDifference": 1
                },
                {
                    "position": 8,
                    "team": {
                        "id": 680,
                        "name": "ADO Den Haag",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 6,
                    "draw": 4,
                    "lost": 7,
                    "points": 22,
                    "goalsFor": 19,
                    "goalsAgainst": 26,
                    "goalDifference": -7
                },
                {
                    "position": 9,
                    "team": {
                        "id": 676,
                        "name": "FC Utrecht",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 5,
                    "draw": 5,
                    "lost": 7,
                    "points": 20,
                    "goalsFor": 26,
                    "goalsAgainst": 32,
                    "goalDifference": -6
                },
                {
                    "position": 10,
                    "team": {
                        "id": 668,
                        "name": "VVV Venlo",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 4,
                    "draw": 7,
                    "lost": 6,
                    "points": 19,
                    "goalsFor": 16,
                    "goalsAgainst": 25,
                    "goalDifference": -9
                },
                {
                    "position": 11,
                    "team": {
                        "id": 684,
                        "name": "PEC Zwolle",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 4,
                    "draw": 4,
                    "lost": 9,
                    "points": 16,
                    "goalsFor": 15,
                    "goalsAgainst": 34,
                    "goalDifference": -19
                },
                {
                    "position": 12,
                    "team": {
                        "id": 672,
                        "name": "Willem II Tilburg",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 4,
                    "draw": 3,
                    "lost": 10,
                    "points": 15,
                    "goalsFor": 19,
                    "goalsAgainst": 34,
                    "goalDifference": -15
                },
                {
                    "position": 13,
                    "team": {
                        "id": 665,
                        "name": "SV Roda JC",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 4,
                    "draw": 2,
                    "lost": 11,
                    "points": 14,
                    "goalsFor": 21,
                    "goalsAgainst": 35,
                    "goalDifference": -14
                },
                {
                    "position": 14,
                    "team": {
                        "id": 681,
                        "name": "NAC Breda",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 2,
                    "draw": 6,
                    "lost": 9,
                    "points": 12,
                    "goalsFor": 15,
                    "goalsAgainst": 26,
                    "goalDifference": -11
                },
                {
                    "position": 15,
                    "team": {
                        "id": 671,
                        "name": "Heracles Almelo",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 2,
                    "draw": 5,
                    "lost": 10,
                    "points": 11,
                    "goalsFor": 21,
                    "goalsAgainst": 39,
                    "goalDifference": -18
                },
                {
                    "position": 16,
                    "team": {
                        "id": 677,
                        "name": "FC Groningen",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 1,
                    "draw": 7,
                    "lost": 9,
                    "points": 10,
                    "goalsFor": 18,
                    "goalsAgainst": 29,
                    "goalDifference": -11
                },
                {
                    "position": 17,
                    "team": {
                        "id": null,
                        "name": null,
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 1,
                    "draw": 4,
                    "lost": 12,
                    "points": 7,
                    "goalsFor": 13,
                    "goalsAgainst": 39,
                    "goalDifference": -26
                },
                {
                    "position": 18,
                    "team": {
                        "id": 666,
                        "name": "FC Twente '65",
                        "crestURI": null
                    },
                    "playedGames": 17,
                    "won": 1,
                    "draw": 3,
                    "lost": 13,
                    "points": 6,
                    "goalsFor": 12,
                    "goalsAgainst": 32,
                    "goalDifference": -20
                }
            ]
        }
    ]
}

            

Available filters: None

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.

venue

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

API behaviour

Request-Throttling

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 result of a game before it has ended, for instance). I tried to set default values so they are convenient for the average user, so every call responds with the most obvious response. However, in most cases these defaults can be overwritten by request attributes.

To protect the API from unnecessary load it is rate limited. Non-authenticated clients are allowed 100 requests per 24 hours and can only access the area and competition list resources.
Registered clients are allowed for 30 requests per minute by default. Score information has a lag of 10-40 seconds, so it's enough to poll the match resource about every 20.

Default values

The API in general always defaults to current dates, which is the current season and matchday. The value for "current season" is usually switched sometime in June. The current matchday is defined by the following algorithm: from now (as of the time it is run every 5 minutes) 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