Why we serve no table rather than half a season
Our source keeps roughly two years of matches. Ask for anything older and it is not an error, it is an empty window. That creates a specific trap, and the honest answer to it is to serve less than we could.
The trap
Suppose we hold a season from January onwards. Real matches, real scores, real scorers. We could compute a table from them and return it. Every field would be populated. Nothing would look broken.
It would also be wrong. Not approximately wrong: a club that led in December and drifted after January appears mid-table, on a points total that matches no published table anywhere. A striker who scored twelve before Christmas appears with three.
Missing data announces itself. Wrong data does not. Someone building on that table gets numbers that are plausible, internally consistent and false, with no error to catch.
The rule
A season is served in full or not at all. On every recomputation we check whether the earliest match we hold is the opening round:
select min(round_num) from matches
where season_id = $1
and (stage = 'league-phase' or (stage is null and coalesce(stage_num, 1) = 1))If that is 1, we hold the season from the start and everything derived from it is sound. If it is 14, thirteen rounds are missing, and the standings, player statistics and team statistics for that season are deleted rather than published.
The competition stays. Its current season is untouched. What goes is the claim to know how a past season went when we only saw the end of it.
What you get instead
A season we do not hold in full is absent from the competition's season list, and asking for it by name returns an error that says so:
{
"error": {
"code": "invalid_season",
"message": "season '2024-25' is not available for eredivisie"
}
}An error you can branch on beats a table you cannot trust.
What it costs us
Several competitions we hold from part-way through 2024-25 and do not serve at all. That is a season of history per competition that we could advertise and do not, on listings where a competitor's comparison table will show a bigger number than ours.
The trade is worth stating plainly. The reason to buy data rather than scrape it is that somebody has checked it. A provider who publishes a half-season table because the column was there is not doing that job, and you cannot tell which kind you bought until something downstream is wrong.
What we do serve
The current season for every competition, and the one before it wherever we hold it from round one. That is what each competition's season list reports, and it is the truth rather than a ceiling we advertise and fall short of.