Skip to content

Retrieving Seasonal Predictions#

In the following example you will retrieve the seasonal predictions for NFL.

Related APIS

Method Description Availability
GET /{sport}/v2/ranks NFL
GET /{sport}/v2/seasonal_performances NFL

Team Seasonal Rankings#

For seasonal team based predictions, start By querying the /{sport}/v2/ranks endpoint for the NFL. Filter by league.uuid and season.season:

GET https://api.quarter4.io/american-football/v2/ranks?league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0&page=1&count=32&season.season=2022

This result contains a list of Ranks entities representing each team and their ranking predictions. For example:

{
  "links": {
    "self": "\/american-football\/v2\/ranks?count=32\u0026league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0\u0026season.season=2022"
  },
  "meta": {
    "totalItems": 32,
    "itemsPerPage": 32,
    "currentPage": 1
  },
  "data": [
    {
      "id": "\/american-football\/v2\/ranks\/a84c4bcf-777a-4d6a-99ed-243c467d3272",
      "type": "Rank",
      "attributes": {
        "additionalWins": 10.612994117647,
        "additionalLosses": 5.3870058823529,
        "totalLosses": 6.3870058823529,
        "totalWins": 10.612994117647,
        "rankNumber": null,
        "rankChange": null,
        "remainingGames": 16,
        "groupRank": 4,
        "playedGames": 1,
        "overtimeLosses": 0,
        "totalOvertimeLosses": null,
        "additionalOvertimeLosses": null,
        "uuid": "a84c4bcf-777a-4d6a-99ed-243c467d3272",
        "leagueRankPred": 8,
        "leagueRankChange": -23,
        "conferenceRankPred": 5,
        "conferenceRankChange": -11,
        "divisionRankPred": 2,
        "leagueRank1": 0.753401805625,
        "leagueRank2": 0.246598194375,
        "leagueRank1OnWin": 1,
        "leagueRank1OnLoss": 0.441675,
        "leagueRank2OnLoss": 0.558325,
        "conferenceRank1": 0.0065048046564039,
        "conferenceRank2": 0.033503637910941,
        "conferenceRank1OnWin": 0.0073497708578965,
        "conferenceRank1OnLoss": 5.4703380692018e-7,
        "conferenceRank2OnLoss": 1.9398219655823e-5,
        "divisionRank1": 0.16906413340216,
        "divisionRank1OnWin": 0.18858970752523,
        "divisionRank1OnLoss": 0.018763015912277,
        "divisionRank": 4,
        "leagueRank": 31,
        "conferenceRank": 16,
        "leagueRank3": 0,
        "leagueRank4": 0,
        "leagueRank5": 0,
        "leagueRank6": 0,
        "leagueRank2OnWin": 0,
        "leagueRank3OnWin": 0,
        "leagueRank4OnLoss": 0,
        "leagueRank5OnLoss": 0,
        "leagueRank6OnLoss": 0,
        "leagueRank4OnWin": 0,
        "leagueRank5OnWin": 0,
        "leagueRank6OnWin": 0,
        "leagueRank3OnLoss": 0,
        "conferenceRank2OnWin": 0.037853565675721,
        "conferenceRank3": 0.065643730247828,
        "conferenceRank4": 0.070849679631379,
        "conferenceRank3OnWin": 0.074138247780161,
        "conferenceRank3OnLoss": 0.00025587176028392,
        "conferenceRank4OnLoss": 0.0018044004151491,
        "leagueRank7": 0,
        "leagueRank8": 0,
        "leagueRank7OnWin": 0,
        "leagueRank7OnLoss": 0,
        "leagueRank8OnLoss": 0,
        "conferenceRank5": 0.057303420312752,
        "conferenceRank4OnWin": 0.079819331618663,
        "conferenceRank5OnWin": 0.063729554690662,
        "conferenceRank5OnLoss": 0.0078372600834836,
        "divisionRank2": 0.25422182055762,
        "divisionRank2OnWin": 0.27477862649706,
        "divisionRank2OnLoss": 0.095982637154018,
        "leagueRank9": 0,
        "leagueRank10": 0,
        "leagueRank11": 0,
        "leagueRank12": 0,
        "leagueRank9OnWin": 0,
        "leagueRank10OnWin": 0,
        "leagueRank11OnWin": 0,
        "leagueRank12OnWin": 0,
        "leagueRank9OnLoss": 0,
        "leagueRank10OnLoss": 0,
        "leagueRank11OnLoss": 0,
        "leagueRank12OnLoss": 0,
        "conferenceRank6": 0.060183521535246,
        "conferenceRank6OnWin": 0.065078529347074,
        "conferenceRank6OnLoss": 0.022503444135099,
        "leagueRank8OnWin": 0,
        "divisionRank3": 0.29866594734001,
        "divisionRank3OnWin": 0.30501022382139,
        "divisionRank3OnLoss": 0.24982990089108,
        "leagueRank13": 0,
        "leagueRank14": 0,
        "leagueRank15": 0,
        "leagueRank16": 0,
        "leagueRank17": 0,
        "leagueRank13OnWin": 0,
        "leagueRank14OnWin": 0,
        "leagueRank15OnWin": 0,
        "leagueRank16OnWin": 0,
        "leagueRank17OnWin": 0,
        "leagueRank13OnLoss": 0,
        "leagueRank14OnLoss": 0,
        "leagueRank15OnLoss": 0,
        "leagueRank16OnLoss": 0,
        "leagueRank17OnLoss": 0,
        "conferenceRank7": 0.089371746456549,
        "conferenceRank8": 0.11806226416264,
        "conferenceRank9": 0.11563039452949,
        "conferenceRank7OnWin": 0.095212804696202,
        "conferenceRank8OnWin": 0.12538636176193,
        "conferenceRank9OnWin": 0.12255546162771,
        "conferenceRank7OnLoss": 0.044409300015279,
        "conferenceRank8OnLoss": 0.061683893578486,
        "conferenceRank9OnLoss": 0.062323622754486,
        "leagueRank18": 0,
        "leagueRank18OnLoss": 0,
        "leagueRank18OnWin": 0,
        "conferenceRank10": 0.084275099908192,
        "conferenceRank10OnWin": 0.088310396612565,
        "conferenceRank10OnLoss": 0.053212781317817,
        "leagueRank19": 0,
        "leagueRank20": 0,
        "leagueRank21": 0,
        "leagueRank19OnWin": 0,
        "leagueRank19OnLoss": 0,
        "leagueRank20OnLoss": 0,
        "leagueRank21OnLoss": 0,
        "conferenceRank11": 0.055795442616346,
        "conferenceRank12": 0.053691804362574,
        "conferenceRank11OnWin": 0.05510308140034,
        "conferenceRank11OnLoss": 0.061124999832773,
        "conferenceRank12OnLoss": 0.1039324809498,
        "divisionRank4": 0.27804809870021,
        "divisionRank4OnLoss": 0.63542444604263,
        "leagueRank22": 0,
        "leagueRank23": 0,
        "leagueRank24": 0,
        "leagueRank25": 0,
        "leagueRank20OnWin": 0,
        "leagueRank21OnWin": 0,
        "leagueRank22OnWin": 0,
        "leagueRank22OnLoss": 0,
        "leagueRank23OnLoss": 0,
        "leagueRank24OnLoss": 0,
        "leagueRank25OnLoss": 0,
        "divisionRank4OnWin": 0.23162144215633,
        "conferenceRank13": 0.066300096074554,
        "conferenceRank12OnWin": 0.047165052791596,
        "conferenceRank13OnWin": 0.055010221926564,
        "conferenceRank13OnLoss": 0.15320564313136,
        "leagueRank26": 0,
        "leagueRank23OnWin": 0,
        "leagueRank24OnWin": 0,
        "leagueRank25OnWin": 0,
        "leagueRank26OnWin": 0,
        "leagueRank26OnLoss": 0,
        "leagueRank27": 0,
        "leagueRank27OnWin": 0,
        "leagueRank27OnLoss": 0,
        "conferenceRank14": 0.062442651591126,
        "conferenceRank14OnWin": 0.050506080280443,
        "conferenceRank14OnLoss": 0.15432624977296,
        "leagueRank28": 0,
        "leagueRank29": 0,
        "leagueRank30": 0,
        "leagueRank31": 0,
        "leagueRank28OnWin": 0,
        "leagueRank28OnLoss": 0,
        "leagueRank29OnLoss": 0,
        "leagueRank30OnLoss": 0,
        "leagueRank31OnLoss": 0,
        "conferenceRank15": 0.038998863468058,
        "conferenceRank15OnLoss": 0.13281961385636,
        "conferenceRank16": 0.021442842535918,
        "conferenceRank15OnWin": 0.026810637281971,
        "conferenceRank16OnLoss": 0.1405404931432,
        "leagueRank32": 0,
        "leagueRank29OnWin": 0,
        "leagueRank30OnWin": 0,
        "leagueRank31OnWin": 0,
        "leagueRank32OnLoss": 0,
        "conferenceRank16OnWin": 0.0059709016505033,
        "leagueRank32OnWin": 0,
        "makeWildcardOne": true,
        "wildcardOne": 0.061660729067225,
        "wildcardOneOnWin": 0.069361918948003,
        "wildcardOneOnLoss": 0.0023796325019024,
        "wildcardTwo": 0.062916024798001,
        "wildcardTwoOnLoss": 0.014418873995166,
        "makeWildcardTwo": false,
        "makeWildcardThree": false,
        "wildcardThree": 0.083618242059126,
        "wildcardThreeOnWin": 0.089453304835506,
        "wildcardThreeOnLoss": 0.038701946620845,
        "wildcardTwoOnWin": 0.069216275445318,
        "rank1": 0.16906413340216,
        "rank1OnWin": 0.18858970752523,
        "rank1OnLoss": 0.018763015912277,
        "rank2": 0.25422182055762,
        "rank2OnWin": 0.27477862649706,
        "rank2OnLoss": 0.095982637154018,
        "rank3": 0.29866594734001,
        "rank3OnWin": 0.30501022382139,
        "rank3OnLoss": 0.24982990089108,
        "rank4": 0.27804809870021,
        "rank4OnWin": 0.23162144215633,
        "rank4OnLoss": 0.63542444604263,
        "rpiWinPercentage": null,
        "rpiOpponentWinPercentage": null,
        "rpiOpponentOpponentWinPercentage": null,
        "rpiRpi": null,
        "rpiRank": null,
        "rpiPredWinPercentage": null,
        "rpiPredOpponentWinPercentage": null,
        "rpiPredOpponentOpponentWinPercentage": null,
        "rpiPredRpi": null,
        "rpiPredRank": null,
        "rpiPredRankChange": null,
        "finalsRank": null
      },
      "relationships": {
        "team": {
          "data": {
            "type": "Team",
            "id": "\/american-football\/v2\/teams\/a163ae9a-bc5e-47e5-9740-f79bca7712c3"
          }
        },
        "league": {
          "data": {
            "type": "League",
            "id": "\/american-football\/v2\/leagues\/38344248-9889-11eb-a8ab-0647cdb505d0"
          }
        },
        "season": {
          "data": {
            "type": "Season",
            "id": "\/american-football\/v2\/seasons\/56bc1528-d0ab-492c-ae3c-ba3656624da1"
          }
        },
        "division": {
          "data": {
            "type": "Division",
            "id": "\/american-football\/v2\/divisions\/2fbc027a-88e4-47f4-9b50-e2bf4b74a00d"
          }
        },
        "conference": {
          "data": {
            "type": "Conference",
            "id": "\/american-football\/v2\/conferences\/cae32df8-33fb-4b80-a8ed-0b0c0a6739d4"
          }
        }
      }
    },
    ...snip...

The result contains a number of probabilities for the teams placement at various rankings within the league, conference and division as well as predictions for total wins/losses and more. Specific attributes will vary by league and/or sport.

Player Seasonal Performance#

For seasonal player based predictions, start By querying the /{sport}/v2/seasonal_performances endpoint for the NFL. Filter by league.uuid and season.season:

GET https://api.quarter4.io/american-football/v2/seasonal_performances?league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0&page=1&count=1&season.season=2022

This result contains a list of the SeasonalPerformance entities and their ranking predictions. For example:

{
  "links": {
    "self": "\/american-football\/v2\/seasonal_performances?count=1\u0026league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0\u0026season.season=2022\u0026page=1",
    "first": "\/american-football\/v2\/seasonal_performances?count=1\u0026league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0\u0026season.season=2022\u0026page=1",
    "last": "\/american-football\/v2\/seasonal_performances?count=1\u0026league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0\u0026season.season=2022\u0026page=19664",
    "next": "\/american-football\/v2\/seasonal_performances?count=1\u0026league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0\u0026season.season=2022\u0026page=2"
  },
  "meta": {
    "totalItems": 19664,
    "itemsPerPage": 1,
    "currentPage": 1
  },
  "data": [
    {
      "id": "\/american-football\/v2\/seasonal_performances\/d4fbcf65-b7de-3c89-b084-5f0660a72f1b",
      "type": "SeasonalPerformance",
      "attributes": {
        "uuid": "d4fbcf65-b7de-3c89-b084-5f0660a72f1b",
        "isStarter": null,
        "eventType": "reg",
        "upcomingGames": 1,
        "upcomingGamesAsStarter": 0,
        "totalGames": 1,
        "totalGamesAsStarter": 0,
        "season": 2022,
        "startDatetime": "2023-01-08T18:00:00+00:00",
        "playedGames": 0,
        "playedGamesAsStarter": 0,
        "positionAbbreviation": "FS",
        "props": {
          "playedDefenseAssists": 0,
          "playedDefenseCombined": 0,
          "playedDefenseInterceptions": 0,
          "playedDefensePassesDefended": 0,
          "playedDefenseSacks": 0,
          "playedDefenseTackles": 0,
          "playedDefenseTloss": 0,
          "totalDefenseAssists": 0.766687,
          "totalDefenseCombined": 4.41041,
          "totalDefenseInterceptions": 0.628632,
          "totalDefensePassesDefended": 1.16424,
          "totalDefenseSacks": 0.0279152,
          "totalDefenseTackles": 3.64372,
          "totalDefenseTloss": 0,
          "upcomingDefenseAssists": 0.766687,
          "upcomingDefenseCombined": 4.41041,
          "upcomingDefenseInterceptions": 0.628632,
          "upcomingDefensePassesDefended": 1.16424,
          "upcomingDefenseSacks": 0.0279152,
          "upcomingDefenseTackles": 3.64372,
          "upcomingDefenseTloss": 0
        }
      },
      "relationships": {
        "player": {
          "data": {
            "type": "Player",
            "id": "\/american-football\/v2\/players\/2b0c20eb-6340-4532-b28d-830f11237506"
          }
        },
        "event": {
          "data": {
            "type": "Event",
            "id": "\/american-football\/v2\/events\/6036c4e4-5860-484f-8fa2-628a8dff4ccc"
          }
        },
        "team": {
          "data": {
            "type": "Team",
            "id": "\/american-football\/v2\/teams\/e60dd861-75f6-4d41-b1f1-d72573529d08"
          }
        }
      }
    }
  ]
}
The result includes a list of props for player performance predictions related to the season. One thing to note abut this is the predictions will change and update after each game. As a result, there will be multiple entries per player for the season but you can use the event as a point in time to know that "As of this event" these are the predications to the season.

For example, with the next event in the season:

GET https://api.quarter4.io/american-football/v2/events?startDate[after]=now&order[startDate]=asc&league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0&page=1&count=1&properties[]=uuid
{
  "links": {
    "self": "\/american-football\/v2\/events?count=1\u0026league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0\u0026order%5BstartDate%5D=asc\u0026properties%5B%5D=uuid\u0026startDate%5Bafter%5D=now\u0026page=1",
    "first": "\/american-football\/v2\/events?count=1\u0026league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0\u0026order%5BstartDate%5D=asc\u0026properties%5B%5D=uuid\u0026startDate%5Bafter%5D=now\u0026page=1",
    "last": "\/american-football\/v2\/events?count=1\u0026league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0\u0026order%5BstartDate%5D=asc\u0026properties%5B%5D=uuid\u0026startDate%5Bafter%5D=now\u0026page=256",
    "next": "\/american-football\/v2\/events?count=1\u0026league.uuid=38344248-9889-11eb-a8ab-0647cdb505d0\u0026order%5BstartDate%5D=asc\u0026properties%5B%5D=uuid\u0026startDate%5Bafter%5D=now\u0026page=2"
  },
  "meta": {
    "totalItems": 256,
    "itemsPerPage": 1,
    "currentPage": 1
  },
  "data": [
    {
      "id": "\/american-football\/v2\/events\/d2554158-f1fe-4fa2-97b5-bf7f076979d4",
      "type": "Event",
      "attributes": {
        "uuid": "d2554158-f1fe-4fa2-97b5-bf7f076979d4"
      }
    }
  ]
}

You can take the uuid of d2554158-f1fe-4fa2-97b5-bf7f076979d4 and use it to query the seasonal performance for the players in that event as of that event start time:

GET https://api.quarter4.io/american-football/v2/seasonal_performances?event.uuid=d2554158-f1fe-4fa2-97b5-bf7f076979d4&page=1&count=1

The results will be filtered to only that event:

{
  "links": {
    "self": "\/american-football\/v2\/seasonal_performances?count=1\u0026event.uuid=d2554158-f1fe-4fa2-97b5-bf7f076979d4\u0026page=1",
    "first": "\/american-football\/v2\/seasonal_performances?count=1\u0026event.uuid=d2554158-f1fe-4fa2-97b5-bf7f076979d4\u0026page=1",
    "last": "\/american-football\/v2\/seasonal_performances?count=1\u0026event.uuid=d2554158-f1fe-4fa2-97b5-bf7f076979d4\u0026page=118",
    "next": "\/american-football\/v2\/seasonal_performances?count=1\u0026event.uuid=d2554158-f1fe-4fa2-97b5-bf7f076979d4\u0026page=2"
  },
  "meta": {
    "totalItems": 118,
    "itemsPerPage": 1,
    "currentPage": 1
  },
  "data": [
    {
      "id": "\/american-football\/v2\/seasonal_performances\/2ef3e334-7875-34a9-b110-148be7071f99",
      "type": "SeasonalPerformance",
      "attributes": {
        "uuid": "2ef3e334-7875-34a9-b110-148be7071f99",
        "isStarter": null,
        "eventType": "reg",
        "upcomingGames": 16,
        "upcomingGamesAsStarter": 16,
        "totalGames": 17,
        "totalGamesAsStarter": 17,
        "season": 2022,
        "startDatetime": "2022-09-16T00:15:00+00:00",
        "playedGames": 1,
        "playedGamesAsStarter": 1,
        "positionAbbreviation": "CB",
        "props": {
          "playedDefenseAssists": 3,
          "playedDefenseCombined": 5,
          "playedDefenseInterceptions": 1,
          "playedDefensePassesDefended": 2,
          "playedDefenseSacks": 0,
          "playedDefenseTackles": 2,
          "playedDefenseTloss": 0,
          "totalDefenseAssists": 9.13272,
          "totalDefenseCombined": 57.6968,
          "totalDefenseInterceptions": 3.45668,
          "totalDefensePassesDefended": 10.6784,
          "totalDefenseSacks": 0.625294,
          "totalDefenseTackles": 48.564,
          "totalDefenseTloss": 1.78424,
          "upcomingDefenseAssists": 6.13272,
          "upcomingDefenseCombined": 52.6968,
          "upcomingDefenseInterceptions": 2.45668,
          "upcomingDefensePassesDefended": 8.67844,
          "upcomingDefenseSacks": 0.625294,
          "upcomingDefenseTackles": 46.564,
          "upcomingDefenseTloss": 1.78424
        }
      },
      "relationships": {
        "player": {
          "data": {
            "type": "Player",
            "id": "\/american-football\/v2\/players\/a71662d8-7b23-435f-8dc4-74f5d896c55f"
          }
        },
        "event": {
          "data": {
            "type": "Event",
            "id": "\/american-football\/v2\/events\/d2554158-f1fe-4fa2-97b5-bf7f076979d4"
          }
        },
        "team": {
          "data": {
            "type": "Team",
            "id": "\/american-football\/v2\/teams\/499a829d-e18d-4b3a-81a8-7aad418fef95"
          }
        }
      }
    }
  ]
}