API policies
See the underneath paragraphs for explanations of the API policies that is: how and why the API acts like it does in several specific scenarios.
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, 30 requests/minute in Standard plan and 60 requests/minute in all plans above.
If the limit is not enough for your use-case, it’s possible to increase it further. Please drop me a line.
Attributes and values
The API embraces null as a valid value. Mostly this happens for values that are not known yet (the score of a game before it started, for instance) or are just not available (attendance for very exotic / lower competitions). Empty lists are valid as well.
Also I stick to true data types, so a score will be returned as an integer and not as a string as in almost any other sports API. I do this because a score is a number and not a character.
Running competitions
This node includes competitions the team started participating at the beginning of the season. Notice a competition will still appear here, even though it might already have been eliminated from the competition. So it might occur that a team holds UEFA Champions- and Euroleague in just one season. The same applies for other attributes as squad (all players that occured in a roster of a team).
Defaults
Defaulting in terms of 'point in time'
In case response data is dependant on date sensitive data, the API defaults to now within UTC timezone. So for example in case you just pull the matches resource
curl -XGET 'https://api.football-data.org/v4/matches/' -H "X-Auth-Token: UR_TOKEN"you will get all matches that happen today. In case you call a Team Resource you get the
squad for the current season.
There are two attributes that matter: current season and current matchday.
Current Matchday
This one is defined by the following algorithm: assuming now as the current point of time, we take the last and the next match of the season. If their matchday is equal, we 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.
So during a season the matchday counts up and only up as I also implemented a rule that does not allow a matchday to switch back (which could happen while catch-up matches are taking place out of order).
Automatic folding
Since v4 I automatically hide deep information in match list views. I realized lots of users just pull lists to quickly gather scores and are not interested in deeper information. I already had such behaviour implemented in v1 but kicked it in v2 as nobody was using it. Now I reintroduce it to be able to set a smart defaults to save bandwith and speed up requests for the majority.
You can control what information gets into your response by setting the following HTTP request headers on any match list subresource.
HTTP Header-Name |
Possible values |
Description |
X-Unfold-Lineups |
[ true | false ] |
Unfold lineups within the reponse or not |
X-Unfold-Bookings |
[ true | false ] |
Unfold bookings within the reponse or not |
X-Unfold-Subs |
[ true | false ] |
Unfold substitutions within the reponse or not |
X-Unfold-Goals |
[ true | false ] |
Unfold goals within the reponse or not |