Probabilities
Enrich your applications with detailed predictions. Our Predictions API offers predictions on various markets like the winner, correct scores, over/under and both teams to score (BTTS) are all available here, produced with our machine learning techniques and models.
Not all fixtures contain sufficient data for reliable predictions. To determine if a fixture is suitable for prediction, use the metadata include to check its "predictable" status.
An overview of all the options to request predictions:
GET Probabilities: returns all probabilities available within your subscription.
GET Performance by League ID: returns the performances of our Predictions Model for your requested league ID.
GET Probabilities by Fixture ID: returns all the predictions available for your requested fixture ID.
For all the predictions endpoints the base URL is the same:
https://api.sportmonks.com/v3/football/predictions
Per endpoint the rest of the URL requires additional information. We will explain this per endpoint.
Please note that you need to have the Predictions add-on in your subscription. The below examples are made with an Enterprise Plan with Predictions.
Requesting probabilities
GET Probabilities as include
One of the most important endpoints you can receive predictions from is the fixtures and livescores endpoints. The predictions are available as an include. The other possibilities listed in this tutorial are only available via the predictions endpoint. While this might be interesting, we understand that using predictions as an add-on is even more flexible. For example, you can use the predictions include on the fixture by date endpoint:
GET All Probabilities
A good starting point is retrieving all the available probabilities within your subscription. To do this, you need to add /probabilities to the base URL of predictions. All you have to do is authorize the request with your API token. Check our authentication section for more info.
Let’s evaluate the response:
id: refers to the id of the probabilityfixture_id: refers to the fixture related to the predictionpredictions: the data object with prediction valuestype_id: refers to the type of the prediction
GET Probabilities by Fixture ID
Not interested in all the probabilities? Just looking for the probabilities of a single fixture? Fear not. You can use the probabilities by fixture id endpoint. Add the fixture id you’re interested in:
https://api.sportmonks.com/v3/football/predictions/probabilities/fixtures/{fixture_id}
For example, if you’re interested in the probabilities for Dundee vs Celtic (fixture id: 18136955).
GET Performance by League ID
The Leagues & performances endpoint will give you information about the performance of our prediction per league. Every league has a performance rating.
Our prediction API continuously updates this rating. 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://api.sportmonks.com/v3/football/predictions/predictability/leagues/{league_id}
For example the performance of the Scottish Premiership (league id 501):
The league predictability consists of four elements.
Hit Ratio Let's take a look at one example. We can see here that for the Scottish Premiership (league id: 501), the ‘hit ratio’ is 0.54 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. 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.
Adding useful information
As you’ve learnt in the includes tutorial, you can enrich your request with includes. This section will discuss some of the most common requests used on the prediction endpoints.
First of all, you can find a list of all available includes on the endpoint pages. For the predictions, there are only 3 includes available:
type: includes the prediction’s type.fixture: includes the fixture information.league: includes the league information.
For example, if you’re interested in the probabilities for Dundee vs Celtic (fixture id: 18136955) with the type and fixture info.
Selecting and filtering
In our filtering tutorial you’ve learnt how to select specific fields or filter only on the data you’re interested in. Our API returns a set of data related to the predictions by default. We can imagine you’re not interested in all the data the API returns.
You’re interested in the probabilities for Dundee vs Celtic (fixture id: 18136955) with the type and fixture info. This results in the below request and response:
Check our filtering tutorial for more tips and tricks.
Last updated