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/coaches/topcoach/{season_uuid}/{league_uuid} | 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"
}
}
}
}
]
}
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"
}
}
}
}
]
}
Top Coach#
This will retrieve a Coach entity representing the top coach for the season. For example:
GET https://api.quarter4.io/american-football/v2/coaches/topcoach/56bc1528-d0ab-492c-ae3c-ba3656624da1/38344248-9889-11eb-a8ab-0647cdb505d0
{
"data": {
"id": "\/american-football\/v2\/coaches\/bb6b1ee0-5cf4-4a35-bb52-9c81e0ddd08e",
"type": "Coach",
"attributes": {
"firstName": "Nick",
"lastName": "Sirianni",
"fullName": "Nick Sirianni",
"position": "Head Coach",
"uuid": "bb6b1ee0-5cf4-4a35-bb52-9c81e0ddd08e",
"combinedName": "Nick Sirianni",
"teamName": "Philadelphia Eagles"
},
"relationships": {
"team": {
"data": {
"type": "Team",
"id": "\/american-football\/v2\/teams\/ff952860-0638-4c8b-9db5-39ac11152f8b"
}
},
"league": {
"data": {
"type": "League",
"id": "\/american-football\/v2\/leagues\/38344248-9889-11eb-a8ab-0647cdb505d0"
}
}
}
}
}
Finals#
To get the winner of the final matchup of the season, use the simulations endpoint and filter on predEventKey=finals with the appropriate season.
For example this will retrieve a Simulation that represents the predicted final event for the 2022 NFL season:
GET https://api.quarter4.io/american-football/v2/simulations?season.season=2022&predEventKey=finals&type.name=REG&include=winner,loser&fields%5Bwinner%5D=uuid,location,nickName&fields%5Bloser%5D=uuid,location,nickName
{
"links": {
"self": "\/american-football\/v2\/simulations?fields%5Bwinner%5D=uuid%2Clocation%2CnickName\u0026fields%5Bloser%5D=uuid%2Clocation%2CnickName\u0026include=winner%2Closer\u0026predEventKey=finals\u0026season.season=2022\u0026type.name=REG"
},
"meta": {
"totalItems": 1,
"itemsPerPage": 30,
"currentPage": 1
},
"data": [
{
"id": "\/american-football\/v2\/simulations\/bf57f520-4e3d-4af5-8311-7d48752fd902",
"type": "Simulation",
"relationships": {
"winner": {
"data": {
"type": "Team",
"id": "\/american-football\/v2\/teams\/72f6be34-9f6b-4620-8d4f-550d443fc0c9"
}
},
"loser": {
"data": {
"type": "Team",
"id": "\/american-football\/v2\/teams\/ff952860-0638-4c8b-9db5-39ac11152f8b"
}
}
}
}
],
"included": [
{
"id": "\/american-football\/v2\/teams\/72f6be34-9f6b-4620-8d4f-550d443fc0c9",
"type": "Team",
"attributes": {
"location": "Buffalo",
"nickName": "Bills",
"uuid": "72f6be34-9f6b-4620-8d4f-550d443fc0c9"
}
},
{
"id": "\/american-football\/v2\/teams\/ff952860-0638-4c8b-9db5-39ac11152f8b",
"type": "Team",
"attributes": {
"location": "Philadelphia",
"nickName": "Eagles",
"uuid": "ff952860-0638-4c8b-9db5-39ac11152f8b"
}
}
]
}
Best Overall#
To get the best overall team of the season, use the ranks endpoint and sort by wins/losses on predEventKey=finals with the appropriate season.
For example this will retrieve a Rank that represents the best overall predicted team for the 2022 NFL season:
GET https://api.quarter4.io/american-football/v2/ranks?season.season=2022&count=1&order%5BtotalWins%5D=desc&order%5BtotalLosses%5D=asc&fields%5BRank%5D=uuid,totalWins,totalLosses&include=team&fields%5Bteam%5D=uuid,location,nickName
{
"data": [
{
"id": "\/american-football\/v2\/ranks\/5a9ca1d5-0e0e-4245-8a7f-159ab2911718",
"type": "Rank",
"attributes": {
"totalLosses": 2.3378588235294,
"totalWins": 14.662141176471,
"uuid": "5a9ca1d5-0e0e-4245-8a7f-159ab2911718"
},
"relationships": {
"team": {
"data": {
"type": "Team",
"id": "\/american-football\/v2\/teams\/ff952860-0638-4c8b-9db5-39ac11152f8b"
}
}
}
}
],
"included": [
{
"id": "\/american-football\/v2\/teams\/ff952860-0638-4c8b-9db5-39ac11152f8b",
"type": "Team",
"attributes": {
"location": "Philadelphia",
"nickName": "Eagles",
"uuid": "ff952860-0638-4c8b-9db5-39ac11152f8b"
}
}
]
}