Football (Soccer) Monte Carlo Season Predictor

Simulates the rest of a football season thousands of times and returns, for every team, the fair probability of finishing first, of taking a continental or promotion place, of reaching the title playoff where the league has one, and of being relegated. If you supply bookmaker implied probabilities, it also reports the gap between the model and the market.

Standings and the remaining calendar come from the public ESPN API. No account, no API key, no configuration.

What makes it different

Almost every football Actor on the Store is a scraper: it copies a table, a fixture list or a set of odds and hands it back to you. This one is a model. It reads public data, builds a strength rating for every team, plays out the real remaining fixture list match by match and returns probabilities you can price against.

It also handles competition formats properly. A league is not always won by the team on top of the table, and not every league relegates three clubs, so the Actor knows how many continental places, playoff places and relegation places each competition actually has.

How it works

1. Current form. Points per game plus a tenth of goal difference per game, taken from the live ESPN standings.
2. Historical baseline. The last three seasons of the same competition, weighted so the most recent counts most. Early in a season a team is mostly its history; by the halfway point it is mostly its current form. Promoted clubs inherit the average of the three weakest teams from the previous campaign.
3. Absences (optional). With your own API-Football key, injured and suspended players shave a little strength off the affected squads, capped at 15 percent.
4. The real calendar. Every match still to be played is pulled from the ESPN fixture list of each team and de-duplicated, so the model knows exactly who plays whom, how many games each side has left and which of them are at home.
5. Simulation. Each iteration draws a slightly different version of every squad from a normal distribution, then plays the whole remaining calendar. Each match becomes a home win, a draw or an away win from the strength gap plus the home advantage. Points are added to the live table and every standings table is ranked separately.
6. Aggregation. Across all iterations the Actor counts how often each team finishes first, inside the qualification places, inside the playoff places and inside the relegation places.
7. Market comparison. Any team you supply a market probability for gets an edge and a value flag.

Because the real calendar is used, strength of schedule falls out of the model for free: a leader with five away trips to the top six is treated very differently from a leader whose run-in is soft.

Competition formats

The regular phase does not mean the same thing everywhere, so the output tells you what it means.

Field	Meaning
titleDecidedBy	table when finishing first wins the trophy, playoff when the regular phase only seeds a knockout stage
fairTitleProbability	Probability of finishing first in the team's own table
fairQualifyProbability	Probability of finishing inside qualifySpots, the headline reward of that competition. Null where the competition has no such threshold
fairPlayoffProbability	Probability of finishing inside playoffSpots. Null where there is no playoff
fairRelegationProbability	Probability of finishing inside relegationSpots. Null where there is no relegation

In the Premier League qualifySpots is 4 for the Champions League, in Brazil it is 4 for the Libertadores group stage, in Liga MX it is 6 for a direct Liguilla place and in MLS it is 7 for a direct playoff berth. So in the Premier League fairTitleProbability really is the title. In Liga MX, the Argentine Liga Profesional, the Colombian Primera A and MLS it is the probability of topping the regular phase, and fairPlayoffProbability is the one that matters for reaching the Liguilla, the cuadrangulares or the postseason.

Leagues split into zones or conferences, such as Argentina and MLS, are ranked table by table rather than merged into one list.

Injury and suspension data: read this before enabling it

The injury adjustment is off by default and everything else works without it. If you switch it on you must bring your own API-Football key. Their free tier only serves seasons 2022 to 2024, so on a free key the current season returns no absences and the Actor simply carries on without the adjustment. It is one request per league per run.

Running it once a day

Standings and fixtures move every matchday. Schedule the Actor to run each morning and you get a fresh probability table without touching anything.

Input

Field	Type	Default	What it does
leagues	array of strings	["eng.1"]	ESPN league slugs to simulate
iterations	integer	2000	Simulated seasons. More is smoother, and slower
historySeasons	integer	3	Past seasons blended into each strength rating. 0 uses current form only
homeAdvantage	number	0.34	Strength added to the home side of every fixture. 0 ignores venue
edgeThreshold	number	0.05	Minimum edge over the market before hasValue turns true
includeInjuries	boolean	false	Turn the absence adjustment on
apiFootballKey	string	empty	Your own API-Football key, only for absences
apiFootballLeagueIds	object	{}	Manual ESPN slug to API-Football id mapping
marketProbabilities	array	[]	Your own implied probabilities, used to compute the edge

Example input

{
    "leagues": ["bra.1", "mex.1", "col.1"],
    "iterations": 4000,
    "historySeasons": 3,
    "homeAdvantage": 0.34,
    "marketProbabilities": [
        { "team": "Palmeiras", "league": "bra.1", "marketProbability": 0.42 }
    ]
}

Output

One item per team. The dataset ships with four ready-made views: Season overview, Market edge, Remaining schedule and Baseline, form and absences.

Field	What it is
league, leagueName, table, team	Competition, its ESPN name, the standings table and the club
gamesPlayed, currentPoints	Live position in the table
remainingGames, homeGamesRemaining	Fixture load still to come
avgRemainingOpponentStrength	How hard the run-in is. Higher is harder
scheduleSource	espn-fixtures when the real calendar was used
projectedAvgFinalPoints	Mean final points across all simulations
titleDecidedBy, qualifySpots, playoffSpots, relegationSpots	The format of that competition
fairTitleProbability	Probability of finishing first in its table
fairQualifyProbability, fairPlayoffProbability, fairRelegationProbability	The other three outcomes
historicalBaseline, currentFormWeight, isNewToLeague	How the strength rating was built
playersInjured, playersSuspended, injuryPenaltyApplied	Absence adjustment, when enabled
marketProbability, edge, hasValue	Comparison against your own odds

Pricing (pay per event)

8.00 USD per 1,000 results. One result is one team, so a 20-team league costs 0.16 USD per run and a daily schedule on a single league is under 5 USD a month.

Supported leagues

Slug	Competition
eng.1, eng.2	Premier League, Championship
esp.1, esp.2	LaLiga, LaLiga 2
ita.1, ger.1, fra.1	Serie A, Bundesliga, Ligue 1
ned.1, por.1, tur.1, bel.1, sco.1	Eredivisie, Primeira Liga, Super Lig, Pro League, Premiership
bra.1	Brasileirao Serie A
mex.1	Liga MX
arg.1	Argentine Liga Profesional
col.1	Colombian Primera A
usa.1	Major League Soccer

Any other ESPN soccer slug also runs. Competitions that are not in the table above fall back to four qualification places, three relegation places and no playoff, so check that this matches the real format before trusting those columns.

Limitations and honest caveats

• The model works from points, goal difference and the calendar. It knows nothing about transfers, managerial changes, weather, fatigue or motivation.
• Draw frequency is estimated from the strength gap rather than modelled from goals, so it is realistic on average but not for a specific fixture.
• Short tournaments such as the Liga MX Apertura or the Colombian Clausura start from a blank table. In the first few rounds the numbers lean heavily on the historical baseline.
• The playoff probability is the probability of reaching the bracket, not of winning it. Knockout rounds are not simulated.
• Relegation by multi-season averages, as used in Argentina and Colombia, is not modelled. Those competitions report no relegation probability at all rather than a wrong one.
• Points deductions, expulsions and mid-season rule changes are not modelled.
• ESPN can be slow to publish fixtures for a competition that has just ended or not yet begun. When no fixture list is available the Actor says so in scheduleSource and falls back to an assumed double round robin.
• These are probabilities, not predictions, and the market is often right. Nothing here is betting advice. Never stake money you cannot afford to lose, and if betting stops being fun, stop.