# Predictions In this last tutorial, we’re going to discuss our [**Prediction API**](https://sportmonks.com/football-api/football-predictions/). We offer the prediction API as a separate [add-on](https://sportmonks.com/football-api/). 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. ### **Our Prediction API** But first, what is included in our prediction API add-on? Our prediction API has three key models: 1. **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) 2. **Valuebet model\*** 3. **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 1. **Timely and substantive**\ The prediction API is updated daily with the latest data from the SportMonks football database 2. **Data controlled**\ No human intervention is needed. The prediction API runs on statistical analysis results, based on the entire historical SportMonks Football Database 3. **Precise probabilities**\ The prediction API offers the most precise probabilities possible, thanks to our mathematical probability distribution models 4. **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**](https://www.sportmonks.com/blogs/sportmonks-prediction-api/). ### **Prediction model** 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: 1. [**Get next probabilities**](https://football-postman.sportmonks.com/#375a3b40-6cea-40f2-b69f-e03376f25644) 2. [**Get probabilities by fixture id**](https://football-postman.sportmonks.com/#298f1fbb-ed79-42d6-aa9d-b5aa5b015611) Let’s start with the first option. #### **Get the next probabilities** [**This endpoint** ](https://football-postman.sportmonks.com/#375a3b40-6cea-40f2-b69f-e03376f25644)will give you all the detected fixtures’ probabilities. This will show all probabilities for every single fixture in your plan. {% hint style="info" %} Probabilities are available 21 days before a game starts {% endhint %} {% tabs %} {% tab title="Request" %} ```javascript https://soccer.sportmonks.com/api/v2.0/predictions/probabilities/next/?api_token={API_TOKEN} ``` {% endtab %} {% tab title="Response" %} ```javascript "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 } } }, ``` {% endtab %} {% endtabs %} 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% {% hint style="info" %} **Note** that the prediction model updates its predictions daily. So, predictions can and will change from day to day. {% endhint %} #### **Get probabilities by fixture id** The second option is to get [**probabilities by fixture id.** ](https://football-postman.sportmonks.com/#298f1fbb-ed79-42d6-aa9d-b5aa5b015611)The only difference is that instead of requesting all fixtures with their probabilities for the next 21 days, you now request one single fixture. ```javascript https://soccer.sportmonks.com/api/v2.0/predictions/probabilities/fixture/{ID}/?api_token={API_TOKEN} ``` As you can see in our [**API reference guide**](https://football-postman.sportmonks.com/)**,** only `fixture` is allowed as an include. However, as you’ve learned from our [**nested includes tutorial,**](/v2/tutorials/enriching-your-response/nested-includes.md) you can enrich the include with a relationship. For example: `&include=fixture.localTeam,fixture.visitorTeam` {% hint style="info" %} **Please note** that you can also use the `&include=probability`on one of our [**fixture endpoints** ](https://football-postman.sportmonks.com/#b7f79045-eac3-40c5-b114-24c5b438f62c)or [**livescores endpoints**](https://football-postman.sportmonks.com/#b850a1c2-9775-4828-8cce-3799532e06aa) {% endhint %} ### **Leagues and performance** The [**Leagues & performances endpoint**](https://football-postman.sportmonks.com/#e0905876-99b9-4747-b678-414b5da58b4e) 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.**](https://sportmonks.com/blogs/profitable-football-predictions/) You can request the performance of the leagues by using the following URL: ```javascript 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: ```javascript "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. 1. **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. 2. **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 3. **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. 4. **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. ### **Value Bet model** 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 = away * `bookmaker`: The name of the bookmaker with the best odd * `odd`: The odd provided by the bookmaker * `is_value`: Indicates if the value bet is still available * `stake`: 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. {% hint style="info" %} **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. {% endhint %} Just like with the probabilities, the value bet API has two options: 1. [**Get next value bets**](https://documenter.getpostman.com/view/11949411/T1LPD6nj?version=latest#306af5a3-5076-4ae6-a35b-3443d8d90e3b): This endpoint will give you all the value bets of the next fixtures. 2. [**Get value bet by fixture id**](https://documenter.getpostman.com/view/11949411/T1LPD6nj?version=latest#64f9ecd9-9b66-47af-bf34-e69b55c50007)**:** This endpoint will give you the value bets of one fixture {% tabs %} {% tab title="Next value bet" %} ```javascript https://soccer.sportmonks.com/api/v2.0/predictions/valuebets/next/?api_token={API_TOKEN} ``` {% endtab %} {% tab title="Value bet by fixture id" %} ```javascript https://soccer.sportmonks.com/api/v2.0/predictions/valuebets/fixture/{ID}?api_token={API_TOKEN} ``` {% endtab %} {% endtabs %} An example of a response: ```javascript "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. * 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. {% hint style="info" %} **Please note** that you can also use the`&include=valuebet`on one of our [**fixture endpoints** ](https://documenter.getpostman.com/view/11949411/T1LPD6nj?version=latest#b7f79045-eac3-40c5-b114-24c5b438f62c)or [**livescores endpoints**](https://documenter.getpostman.com/view/11949411/T1LPD6nj?version=latest#b850a1c2-9775-4828-8cce-3799532e06aa)**.** {% endhint %} Next up is Sportmonks' ID Finder. The easiest tool to find all ID's you need. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sportmonks.com/v2/tutorials/odds-and-predictions/extra-predictions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.