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.

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:

https://api.sportmonks.com/v3/football/fixtures/between/2022-12-09/2022-12-10?api_token=YOUR_TOKEN&filters=fixtureLeagues:732&include=predictions;participants
Response
{
  "data": [
    {
      "id": 18452329,
      "sport_id": 1,
      "league_id": 732,
      "season_id": 18017,
      "stage_id": 77452384,
      "group_id": null,
      "aggregate_id": null,
      "round_id": null,
      "state_id": 8,
      "venue_id": 338812,
      "name": "Croatia vs Brazil",
      "starting_at": "2022-12-09 15:00:00",
      "result_info": "Croatia won after penalties.",
      "leg": "1/1",
      "details": null,
      "length": 90,
      "placeholder": false,
      "has_odds": true,
      "starting_at_timestamp": 1670598000,
      "participants": [
        {
          "id": 18704,
          "sport_id": 1,
          "country_id": 5,
          "venue_id": 392,
          "gender": "male",
          "name": "Brazil",
          "short_code": "BRA",
          "image_path": "https://cdn.sportmonks.com/images/soccer/teams/16/18704.png",
          "founded": 1914,
          "type": "national",
          "placeholder": false,
          "last_played_at": "2023-06-20 19:00:00",
          "meta": {
            "location": "away",
            "winner": false,
            "position": 1
          }
        },
        {
          "id": 18588,
          "sport_id": 1,
          "country_id": 266,
          "venue_id": 176,
          "gender": "male",
          "name": "Croatia",
          "short_code": "CRO",
          "image_path": "https://cdn.sportmonks.com/images/soccer/teams/28/18588.png",
          "founded": 1912,
          "type": "national",
          "placeholder": false,
          "last_played_at": "2023-06-18 18:45:00",
          "meta": {
            "location": "home",
            "winner": true,
            "position": 2
          }
        }
      ],
      "predictions": [
        {
          "id": 3297856,
          "fixture_id": 18452329,
          "predictions": {
            "yes": 52.75,
            "no": 47.25
          },
          "type_id": 235
        },
        {
          "id": 3297853,
          "fixture_id": 18452329,
          "predictions": {
            "home": 25.2,
            "away": 50.5,
            "draw": 24.3
          },
          "type_id": 237
        },
        {
          "id": 3297857,
          "fixture_id": 18452329,
          "predictions": {
            "yes": 31,
            "no": 69
          },
          "type_id": 236
        },
        {
          "id": 3297860,
          "fixture_id": 18452329,
          "predictions": {
            "yes": 78.96,
            "no": 21.04
          },
          "type_id": 333
        },
        {
          "id": 3297859,
          "fixture_id": 18452329,
          "predictions": {
            "yes": 60.74,
            "no": 39.26
          },
          "type_id": 334
        },
        {
          "id": 3297862,
          "fixture_id": 18452329,
          "predictions": {
            "yes": 48.7,
            "no": 51.3
          },
          "type_id": 332
        },
        {
          "id": 3297858,
          "fixture_id": 18452329,
          "predictions": {
            "scores": {
              "0-0": 6.44,
              "0-1": 10.44,
              "0-2": 8.56,
              "0-3": 4.74,
              "1-0": 6.83,
              "1-1": 11.25,
              "1-2": 9.39,
              "1-3": 5.28,
              "2-0": 3.71,
              "2-1": 6.22,
              "2-2": 5.28,
              "2-3": 3.02,
              "3-0": 1.38,
              "3-1": 2.35,
              "3-2": 2.02,
              "3-3": 1.18,
              "Other_1": 2.67,
              "Other_2": 9.06,
              "Other_X": 0.17
            }
          },
          "type_id": 240
        },
        
// And more

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.

https://api.sportmonks.com/v3/football/predictions/probabilities?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 2931809,
      "fixture_id": 18117749,
      "predictions": {
        "yes": 55.602,
        "no": 44.399
      },
      "type_id": 235
    },
    {
      "id": 2931810,
      "fixture_id": 18117749,
      "predictions": {
        "yes": 33.23,
        "no": 66.771
      },
      "type_id": 236
    },
    {
      "id": 2931811,
      "fixture_id": 18117749,
      "predictions": {
        "yes": 75.773,
        "no": 24.228
      },
      "type_id": 334
    },
    // and more

Letโ€™s evaluate the response:

  • id: refers to the id of the probability

  • fixture_id: refers to the fixture related to the prediction

  • predictions: the data object with prediction values

  • type_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).

https://api.sportmonks.com/v3/football/predictions/probabilities/fixtures/18136955?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 130437,
      "fixture_id": 18136955,
      "predictions": {
        "home": 17.122,
        "away": 59.864,
        "draw": 23.014
      },
      "type_id": 237
    },
    {
      "id": 130438,
      "fixture_id": 18136955,
      "predictions": {
        "yes": 57.887,
        "no": 42.113
      },
      "type_id": 231
    },
    {
      "id": 130439,
      "fixture_id": 18136955,
      "predictions": {
        "home_home": 7.466,
        "home_away": 2.83,
        "home_draw": 4.265,
        "away_home": 1.54,
        "away_away": 42.96,
        "away_draw": 5.093,
        "draw_draw": 11.702,
        "draw_home": 7.561,
        "draw_away": 16.581
      },
      "type_id": 232
    },

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):

https://api.sportmonks.com/v3/football/predictions/predictability/leagues/501?api_token=YOUR_TOKEN
Response
{
  "data": [
    {
      "id": 134,
      "league_id": 501,
      "type_id": 244,
      "data": {
        "fulltime_result": "unchanged",
        "away_over_under_0_5": null,
        "away_over_under_1_5": null,
        "both_teams_to_score": "unchanged",
        "team_to_score_first": "unchanged",
        "home_over_under_0_5": null,
        "home_over_under_1_5": null,
        "over_under_1_5": "unchanged",
        "over_under_2_5": "unchanged",
        "over_under_3_5": "up",
        "correct_score": "unchanged",
        "ht_ft": "up",
        "fulltime_result_1st_half": "up"
      }
    },
    {
      "id": 133,
      "league_id": 501,
      "type_id": 243,
      "data": {
        "fulltime_result": "high",
        "away_over_under_0_5": null,
        "away_over_under_1_5": null,
        "both_teams_to_score": "poor",
        "team_to_score_first": "high",
        "home_over_under_0_5": null,
        "home_over_under_1_5": null,
        "over_under_1_5": "medium",
        "over_under_2_5": "poor",
        "over_under_3_5": "poor",
        "correct_score": "high",
        "ht_ft": "high",
        "fulltime_result_1st_half": "high"
      }
    },
    //And more

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 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.

  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. 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.

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.

https://api.sportmonks.com/v3/football/predictions/probabilities/fixtures/18136955?api_token={your_token}&include=type;fixture
Response

  "data": [
    {
      "id": 130437,
      "fixture_id": 18136955,
      "predictions": {
        "home": 17.122,
        "away": 59.864,
        "draw": 23.014
      },
      "type_id": 237,
      "type": {
        "id": 237,
        "name": "Fulltime Result Probability",
        "code": "fulltime-result-probability",
        "developer_name": "FULLTIME_RESULT_PROBABILITY",
        "model_type": "prediction",
        "stat_group": null
      },
      "fixture": {
        "id": 18136955,
        "sport_id": 1,
        "league_id": 501,
        "season_id": 18369,
        "stage_id": 77453684,
        "group_id": null,
        "aggregate_id": null,
        "round_id": 247443,
        "state_id": 5,
        "venue_id": 284597,
        "name": "Dundee vs Celtic",
        "starting_at": "2021-11-07 12:00:00",
        "result_info": "Celtic won after full-time.",
        "leg": "1/1",
        "details": null,
        "length": 90,
        "placeholder": false,
        "last_processed_at": "2023-03-02 17:54:33",
        "has_odds": true,
        "starting_at_timestamp": 1636286400
      }
    },
    //And more

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:

https://api.sportmonks.com/v3/football/predictions/probabilities/fixtures/18136955?api_token=YOUR_TOKEN&include=type:name;fixture:name
Response
{
  "data": [
    {
      "id": 130437,
      "fixture_id": 18136955,
      "predictions": {
        "home": 17.122,
        "away": 59.864,
        "draw": 23.014
      },
      "type_id": 237,
      "type": {
        "id": 237,
        "name": "Fulltime Result Probability"
      },
      "fixture": {
        "id": 18136955,
        "sport_id": 1,
        "round_id": 247443,
        "stage_id": 77453684,
        "group_id": null,
        "aggregate_id": null,
        "league_id": 501,
        "season_id": 18369,
        "venue_id": 284597,
        "state_id": 5,
        "name": "Dundee vs Celtic",
        "starting_at_timestamp": null
      }
    },
    {
      "id": 130438,
      "fixture_id": 18136955,
      "predictions": {
        "yes": 57.887,
        "no": 42.113
      },
      "type_id": 231,
      "type": {
        "id": 231,
        "name": "Both Teams To Score Probability"
      },
      "fixture": {
        "id": 18136955,
        "sport_id": 1,
        "round_id": 247443,
        "stage_id": 77453684,
        "group_id": null,
        "aggregate_id": null,
        "league_id": 501,
        "season_id": 18369,
        "venue_id": 284597,
        "state_id": 5,
        "name": "Dundee vs Celtic",
        "starting_at_timestamp": null
      }
    },
    //And more

Check our filtering tutorial for more tips and tricks.

Last updated