Soccer Predictions API — Title, Top-4, Playoff and Relegation Odds

Get football (soccer) season predictions as structured data, not as a web page. This Actor replays the rest of the season thousands of times on the real remaining calendar 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. Supply bookmaker implied probabilities and it also reports the gap between the model and the market.

Prediction tables are published all over the web, but almost never as an API you can pull into a spreadsheet, a model or an AI agent. This Actor computes them from scratch and hands you clean JSON, CSV, Excel or an API endpoint.

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

Who uses this

Use case	What you do with it
Betting models	Compare fair probabilities against outright markets — title, top four, relegation — and act on the edge column
Fantasy football	Run-in difficulty shows whose fixtures ease up over the next two months
Sports media and blogs	A defensible title-race or relegation-battle table you generated yourself, refreshed every morning
Data science	Projected points and per-team strength ratings as a feature set for your own models
Dashboards	A daily scheduled run feeding Google Sheets, a database, or a BI tool
AI agents	A tool that returns real computed probabilities instead of hallucinated ones

Quick start

Run it with the default input and it projects the Premier League:

{}

Several leagues at once:

{
  "leagues": ["eng.1", "esp.1", "ita.1", "ger.1", "fra.1"],
  "iterations": 5000
}

You can also call it straight from the Apify API:

curl -X POST "https://api.apify.com/v2/acts/commodus67~football-soccer-monte-carlo-predictor/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "leagues": ["eng.1", "esp.1"] }'

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
archiveToNamedDataset	string	empty	Name of a dataset in your account to also append this run's rows to. Named datasets are kept indefinitely, so scheduled runs accumulate a permanent history. See “Build your own history” below

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
retrievedAt, simulations	When the snapshot was taken and how many seasons were simulated

Build your own history

A run's own dataset is temporary — Apify deletes it 31 days after the run. A named dataset is kept indefinitely.

Set archiveToNamedDataset to a name such as soccer-odds-history and every run appends its rows to that dataset as well as writing its normal one. Point a daily schedule at it and you accumulate your own record of how each team's title, top-four, playoff and relegation probabilities moved across the season — a time series you cannot reconstruct afterwards, because the table and remaining fixtures that produced each snapshot no longer exist.

Every row already carries retrievedAt, league and simulations, so stacked snapshots are never ambiguous: you always know when a projection was taken, for which competition, and how many simulated seasons it came from.

The named dataset is created the first time it is used and lives in your account under Storage → Datasets. Leave the field empty and nothing changes: you get the normal run dataset only.

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.

FAQ

Is this a soccer predictions API? Yes. Every run writes a dataset you can read as JSON or CSV over HTTP, and the Actor can be started from the Apify API or an MCP client. There is no key to request and no rate limit to negotiate.

Where does the data come from? Live standings and the remaining calendar come from the public ESPN API. No account or API key of your own is required for that.

Does it work before the season starts? Yes. With no matches played the model leans entirely on the historical baseline of the last three seasons, and shifts towards current form as the campaign progresses.

Can it handle leagues with playoffs, like MLS or Liga MX? Yes. The Actor reads the competition format and returns playoff probabilities and the correct spot counts rather than forcing a European table onto it. See Competition formats above.

What about leagues with a split table, like Scotland? The output reports which table a team sits in, so split and conference formats come back mapped to the right rewards.

How do I include injuries and suspensions? Set includeInjuries to true and supply your own API-Football key. Read the section above first — their free tier only covers seasons 2022 to 2024, so the current season needs a paid plan on their side.

Can I use it to find value bets? Yes. Supply your market implied probabilities and the output returns the edge per team and flags anything clearing your threshold.

How many iterations should I run? 2,000 is the default and is fine for a single league. Raise it if you are simulating several leagues at once or care about the tails.

Is there a version for baseball? Yes — the MLB Playoff Odds API runs the same approach across all 30 Major League Baseball teams, with division, wild card, playoff and top-seed probabilities.

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.

---

Not affiliated with, endorsed by, or sponsored by ESPN or any league or competition named above. For informational and research use.