Predictions
In this last tutorial, we’re going to discuss our Prediction API. We offer the prediction API as a separate add-on. Meaning, you will need to have a plan with this add-on to have access to our prediction model. We’re going to discuss what you can do with the prediction API and how it works.
But first, what is included in our prediction API add-on? Our prediction API has three key models:
Prediction model (based on Bayesian principles)
Probabilities per match (domestic leagues only) - Winner predictions (home win, away win or draw) - BTTS (Both Teams To Score) prediction - Correct score predictions - Over/under probabilities
Leagues and performance (measuring the performance of probabilities)
Valuebet model*
Player contribution model**
* The valuebet model processes thousands and thousands of historical odds data and market trends in order to find value opportunities, which are then compared against bookmaker odds. ** Used to calculate probabilities of international cups. The last known line-up is used for the calculations of probabilities. As soon as the new line-up is known, the probability will also be re-calculated
All three models and algorithms are based on four key principles
Timely and substantive The prediction API is updated daily with the latest data from the SportMonks football database
Data controlled No human intervention is needed. The prediction API runs on statistical analysis results, based on the entire historical SportMonks Football Database
Precise probabilities The prediction API offers the most precise probabilities possible, thanks due to our mathematical probability distribution models
Predictability performance
The success rate and quality of our prediction API are monitored by us, but you can also track our predictions’ performance yourself.
For a full overview of the technology behind our predictions, you can refer to our blog.
The prediction model makes predictions about the possible outcomes of fixtures, such as the probability that the home or away team wins, but also the probability of a draw.
The prediction model is created with the latest machine learning techniques and can thus offer you the best predictions possible
The prediction model offers various probabilities and we’re going to show you how to request them and how you should interpret them.
There are actually two options to request the fixture probability:
Let’s start with the first option.
This endpoint will give you all the detected fixtures’ probabilities. This will show all probabilities for every single fixture in your plan.
Probabilities are available 21 days before a game starts
https://soccer.sportmonks.com/api/v2.0/predictions/probabilities/next/?api_token={API_TOKEN}
"data": [{"fixture_id": 17361016,"predictions": {"btts": 37.396,"over_2_5": 32.302,"under_2_5": 67.699,"over_3_5": 14.267,"under_3_5": 85.734,"HT_over_0_5": 52.182,"HT_under_0_5": 47.819,"HT_over_1_5": 16.903,"HT_under_1_5": 83.098,"AT_over_0_5": 71.667,"AT_under_0_5": 28.334,"AT_over_1_5": 35.934,"AT_under_1_5": 64.066,"home": 21.768,"away": 48.823,"draw": 29.409,"correct_score": {"0-0": 13.54,"0-1": 17.08,"0-2": 10.77,"0-3": 4.529,"0-4": 1.428,"0-5": 0.36,"0-6": 0.076,"0-7": 0.014,"0-8": 0.002,"1-0": 9.996,"1-1": 12.6,"1-2": 7.949,"1-3": 3.341,"1-4": 1.053,"1-5": 0.266,"1-6": 0.056,"1-7": 0.01,"1-8": 0.002,"2-0": 3.687,"2-1": 4.65,"2-2": 2.932,"2-3": 1.233,"2-4": 0.389,"2-5": 0.098,"2-6": 0.021,"2-7": 0.004,"2-8": 0.001,"3-0": 0.907,"3-1": 1.143,"3-2": 0.721,"3-3": 0.303,"3-4": 0.096,"3-5": 0.024,"3-6": 0.005,"3-7": 0.001,"4-0": 0.167,"4-1": 0.211,"4-2": 0.133,"4-3": 0.056,"4-4": 0.018,"4-5": 0.004,"4-6": 0.001,"5-0": 0.025,"5-1": 0.031,"5-2": 0.02,"5-3": 0.008,"5-4": 0.003,"5-5": 0.001,"6-0": 0.003,"6-1": 0.004,"6-2": 0.002,"6-3": 0.001}}},
This might seem like a lot of data at first, but it is quite straightforward actually. Let’s walk through the data together.
First thing we see is ‘BTTS’, which means Both Teams To Score. The probability that both teams will score a goal is roughly 55%. Next, we see: over 2.5 is roughly 51%, meaning that there’s a 51% chance that there will be over two and a half goals in the game. HT and AT under/over indicate the respective probabilities for the home and away teams. Finally, correct score is a bunch of probabilities for each possible score. So, a final score of 1-1 has a probability of 12.2%
Note that the prediction model updates its predictions daily. So, predictions can and will change from day to day.
The second option is to get probabilities by fixture id. The only difference is that instead of requesting all fixtures with their probabilities for the next 21 days, you now request one single fixture.
https://soccer.sportmonks.com/api/v2.0/predictions/probabilities/fixture/{ID}/?api_token={API_TOKEN}
As you can see in our API reference guide, only fixture is allowed as an include. However, as you’ve learned from our nested includes tutorial, you can enrich the include with a relationship. For example:
&include=fixture.localTeam,fixture.visitorTeam
Please note that you can also use the &include=probabilityon one of our fixture endpoints or livescores endpoints
The Leagues & performances endpoint will give you information about which leagues are included in our prediction API and what the performance is per league.
Every league has a performance rating. This rating is continuously updated by our prediction API. The league predictability is a set of metrics that measures the quality and predictive power of the model. For more information about our model, please refer to our prediction blog.
You can request the performance of the leagues by using the following URL:
https://soccer.sportmonks.com/api/v2.0/predictions/leagues/?api_token={API_TOKEN}
This will return predictions for all the leagues in your subscription. As well as the league’s performance.
For example:
"id": 271,"active": true,"type": "domestic","legacy_id": 43,"country_id": 320,"logo_path": "https://cdn.sportmonks.com/images/soccer/leagues/271.png","name": "Superliga","is_cup": false,"current_season_id": 17328,"current_round_id": 199459,"current_stage_id": 77447994,"live_standings": true,"coverage": {"predictions": true,"topscorer_goals": true,"topscorer_assists": true,"topscorer_cards": true},"predictability": {"data": {"league_id": 271,"hit_ratio": "0.48","log_loss": -1.0143,"predictability": "medium","predictive_power": "up","historical_log_loss": {"3ways-ft": -1.0599,"away_overunder05": -0.4971,"away_overunder15": -0.668,"btts": -0.6459,"home_overunder05": -0.47,"home_overunder15": -0.7071,"overunder15": -0.4484,"overunder25": -0.6738,"overunder35": -0.6716,"scores": -2.7948},"model_hit_ratio": {"3ways-ft": 0.48,"away_overunder05": 0.82,"away_overunder15": 0.65,"btts": 0.64,"home_overunder05": 0.83,"home_overunder15": 0.6,"overunder15": 0.72,"overunder25": 0.51,"overunder35": 0.64,"scores": 0.15},"model_predictability": {"3ways-ft": "up","away_overunder05": "up","away_overunder15": "unchanged","btts": "up","home_overunder05": "unchanged","home_overunder15": "up","overunder15": "up","overunder25": "up","overunder35": "up","scores": "unchanged"},"model_predictive_power": {"3ways-ft": "up","away_overunder05": "up","away_overunder15": "unchanged","btts": "up","home_overunder05": "unchanged","home_overunder15": "up","overunder15": "up","overunder25": "up","overunder35": "up","scores": "unchanged"},"model_log_loss": {"3ways-ft": -1.0143,"away_overunder05": -0.5259,"away_overunder15": -0.6774,"btts": -0.6713,"home_overunder05": -0.4807,"home_overunder15": -0.7004,"overunder15": -0.4543,"overunder25": -0.6931,"overunder35": -0.6676,"scores": -2.7602},"updated_at": {"date": "2020-12-18 21:00:06.000000","timezone_type": 3,"timezone": "UTC"}}}},
What do we see exactly? The league predictability tells you about the prediction performance of that league. Let’s discuss this.
The league predictability consists of four elements.
Hit Ratio
Let's take a look at one example. We can see here that for the Danish Superliga (league id: 271), the ‘hit ratio’ is 0.48 for the 3-way result (1, X, 2) market. The hit ratio is the number of times the model predicted the particular market correctly the last 100 matches of the league. The closer to 1,00, the better it is. You can track and see the real-time predictability performance for all prediction markets per league.
Log Loss
This is the average log loss over the last 100 matches of the league. It measures the quality of the probabilities. The closer the number is to 0, the better it is. The quality is considered poor, medium, good or high based on the log loss.
Poor is < -1.07
Medium is > -1.07
Good is > -1.02
High is > -.98
Predictability
Not everybody is comfortable with numbers. The predictability is the same poor, medium, good, and high as from log loss. However, this will tell you straight away in words, whether the predictability of the league is good or bad.
Predictive power
This tells you whether the log loss has been increasing or not, in the last 50 matches. Possible outcomes are up, down, or unchanged. If the predictive power is up, then the league becomes more predictable.
The Value Bet model processes thousands of historical odds data and market trends to find the best value opportunities. In other words, it compares bookmakers odds with each other and then gives you the best value bookmaker.
Once the opening odds are available, the value detection algorithm runs every 10 minutes up to the beginning of the match. Each value detected by the model comes with a set of features described below.
bet: 1 = home, x = draw, 2 = awaybookmaker: The name of the bookmaker with the best oddodd: The odd provided by the bookmakeris_value: Indicates if the value bet is still availablestake: The stake helps manage the risk that the model would take in the bet. The risk is measured with the volatility of the profit and loss of the value bet strategy. The stake is calculated to have an average risk of one unit.fair_odd: Our algorithm allows you to find the fair odd of a value. The fair odd is useful to play against bookmakers that are not listed in SportMonks. Any odd above the fair odd can be considered as value.
Please note that our algorithm detects Value Bets based on all available odds in combination with the fair odd calculated by the Value Bet algorithm. Therefore, not every match has a Value Bet available.
Just like with the probabilities, the value bet API has two options:
Get next value bets: This endpoint will give you all the value bets of the next fixtures.
Get value bet by fixture id: This endpoint will give you the value bets of one fixture
https://soccer.sportmonks.com/api/v2.0/predictions/valuebets/next/?api_token={API_TOKEN}
https://soccer.sportmonks.com/api/v2.0/predictions/valuebets/fixture/{ID}?api_token={API_TOKEN}
An example of a response:
"valuebet": {"data": {"fixture_id": 11976124,"predictions": {"bet": "2","bookmaker": "bet365","odd": 19,"is_value": true,"stake": 0.76,"fair_odd": 16.4}}
Bet has the possible value of 1, X or 2. This represents the 3-Way Result market.
1 = home
X = draw
2 = away
The bookmaker’s name is bet365.
bet365 provides an odd of 19.
The stake assists in managing the risk that the model would take in the bet. The risk is measured with the volatility of the profit and loss of the Value Bet Strategy. The stake is calculated in order to have an average risk of one unit. More information about our model can be found here.
The fair odd is calculated with our algorithm. It’s the fair odd of a value. Any odd above the fair odd can be considered as value.
Please note that you can also use the&include=valuebeton one of our fixture endpoints or livescores endpoints.
Next up are the how-to guides. You don't have to follow the how-to guides in any set order. If there are still things relatively unclear, don't hesitate to contact our support team.