Retrieving NCAA Tournament Predictions#

In the following example you will retrieve information for the 2021 NCAA Men's Basketball Conference Tournaments.

Related APIS

Method	Description	Availability
`GET`	/{sport}/v2/leagues	All Leagues
`GET`	/{sport}/v2/events	All Leagues
`GET`	/{sport}/v2/tournaments	NCAAMB
`GET`	/{sport}/v2/rounds	All Leagues
`GET`	/{sport}/v2/simulations	NCAAMB

In order to load tournament info via the API, you will need to know the UUID of the tournament. Start by querying the tournaments endpoint and get the uuid for the 2021 Big South tournament. To locate this tournament, filter by the season and only ask for the NCAAMB league (uuid da57437e-4688-4e1c-9bc5-6df2dcab1a14 which can be found by querying /basketball/v2/leagues)

GET https://api.quarter4.io/basketball/v2/tournaments?count=100&season.season=2021&league.uuid=da57437e-4688-4e1c-9bc5-6df2dcab1a14

This result contains a list of tournaments. Locate the Big South tournament and note the uuid. You will use it later to filter queries:

    ...snip...
        {
      "id": "\/basketball\/v2\/tournaments\/93b34d91-e6b7-421a-ac9a-1edbc4924526",
      "type": "Tournament",
      "attributes": {
        "_type": {
          "uuid": "7a9a0425-8204-11eb-984a-0295de2bb36c"
        },
        "name": "Big South",
        "location": "Charlotte, NC, USA",
        "startDate": "2022-03-02T00:00:00+00:00",
        "endDate": "2022-03-06T00:00:00+00:00",
        "uuid": "93b34d91-e6b7-421a-ac9a-1edbc4924526",
        "displayStatus": "inprogress"
      },
      "relationships": {
        "league": {
          "data": {
            "type": "League",
            "id": "\/basketball\/v2\/leagues\/da57437e-4688-4e1c-9bc5-6df2dcab1a14"
          }
        },
        "rounds": {
          "data": [
            {
              "type": "Round",
              "id": "\/basketball\/v2\/rounds\/576d0d70-75ab-4e34-a81b-a592ed744155"
            },
            {
              "type": "Round",
              "id": "\/basketball\/v2\/rounds\/b998a8a7-4b8b-471e-b2e5-553d9b117b0c"
            },
            {
              "type": "Round",
              "id": "\/basketball\/v2\/rounds\/4cb9d29c-f05b-41a0-8a6b-02ae3ca234c0"
            },
            {
              "type": "Round",
              "id": "\/basketball\/v2\/rounds\/d069597f-6df2-47f7-8143-8ad8397ca600"
            }
          ]
        }
      }
    },
    ...snip...

You will see that the tournament's UUID is 93b34d91-e6b7-421a-ac9a-1edbc4924526.

You can get game events for each individual round using the information in the round relationships id, for example:

GET https://api.quarter4.io/basketball/v2/rounds/576d0d70-75ab-4e34-a81b-a592ed744155

or you can retrieve info for all rounds for the tournament in one query using the tournament uuid in the query string:

GET https://api.quarter4.io/basketball/v2/rounds?tournament.uuid=93b34d91-e6b7-421a-ac9a-1edbc4924526

For example this returns all the rounds in the Big South tournament:

{
  "links": {
    "self": "\/basketball\/v2\/rounds?tournament.uuid=93b34d91-e6b7-421a-ac9a-1edbc4924526"
  },
  "meta": {
    "totalItems": 4,
    "itemsPerPage": 30,
    "currentPage": 1
  },
  "data": [
    {
      "id": "\/basketball\/v2\/rounds\/b998a8a7-4b8b-471e-b2e5-553d9b117b0c",
      "type": "Round",
      "attributes": {
        "sequence": 1,
        "name": "Round 1",
        "uuid": "b998a8a7-4b8b-471e-b2e5-553d9b117b0c",
        "winPercents": {
          "686abcdc-e822-40fd-99b0-be1d17eff132": 72,
          "372f9f0d-ab05-43cd-8f81-f9d4921014ad": 28,
          "acfa3baa-b95d-4e88-9acf-3092b34bb503": 84,
          "2b05d00c-f473-4351-95b4-89aab73a856f": 16,
          "5554f09c-347f-4ce2-beff-80c6607fdc18": 62,
          "00efea9b-7dcb-45db-9b14-21472ad8f6a8": 38,
          "070b8684-f908-4f45-94dd-babf5cd2f8ad": 54,
          "83f11843-a123-4fcc-8b1c-a8c60560907d": 46
        }
      },
      "relationships": {
        "tournament": {
          "data": {
            "type": "Tournament",
            "id": "\/basketball\/v2\/tournaments\/93b34d91-e6b7-421a-ac9a-1edbc4924526"
          }
        },
        "events": {
          "data": [
            {
              "type": "Event",
              "id": "\/basketball\/v2\/events\/96ca2381-196b-4e78-b5e5-f67614a0ad43"
            },
            {
              "type": "Event",
              "id": "\/basketball\/v2\/events\/a2640dd0-5a74-4bea-833d-acc060211ff8"
            },
            {
              "type": "Event",
              "id": "\/basketball\/v2\/events\/bd166fb3-64ed-48d5-bd94-d9b31a46880e"
            },
            {
              "type": "Event",
              "id": "\/basketball\/v2\/events\/82fa6cbb-c4f1-498d-83f4-78a0e4027570"
            }
          ]
        },
        "brackets": {
          "data": [
            {
              "type": "Bracket",
              "id": "\/basketball\/v2\/brackets\/77f3e17e-c101-3ff9-9a23-b896485ac42c"
            }
          ]
        }
      }
    },

    ...snip...

The above result includes a quick shortcut in the data[0].attributes.winPercents value. This is a json object keyed to a team's uuid and will give you the win percent for each team playing in the game events for this round. If you have previously loaded the events and/or teams and have cached their uuids cached, you can quickly update the predicted win percents in your cache using these values. Otherwise, you will need to query each of the events.

You can query each event using the information in the id of the events relationship as follows:

GET https://api.quarter4.io/basketball/v2/events/96ca2381-196b-4e78-b5e5-f67614a0ad43?include=winloss,simulatedPicks

Here, we've also included &include=winloss,simulatedPicks on the url here to retrieve the related WinLoss and Simulation entities for the event. The result is something like this:

{
  "data": {
    "id": "\/basketball\/v2\/events\/96ca2381-196b-4e78-b5e5-f67614a0ad43",
    "type": "Event",
    "attributes": {
      "startDate": "2022-03-02T16:30:00+00:00",
      "eventStatus": {
        "name": "Closed",
        "uuid": "7ff6078d-8111-40a3-b479-99b02ee1fcaf"
      },
      "homeTeamScore": 71,
      "awayTeamScore": 78,
      "title": "Big South - First Round - Game 1",
      "homeSeed": 8,
      "awaySeed": 9,
      "coverage": "full",
      "otherBooksData": {
        "spread_home": {
          "MGM": "1.5",
          "DraftKings": "2",
          "FanDuel": "1.5",
          "Westgate": "1.5",
          "SugarHouseNJ": "1.5",
          "PointsBet": "1.5",
          "WilliamHillNewJersey": "1"
        },
        "spread_away": {
          "MGM": "-1.5",
          "DraftKings": "-2",
          "FanDuel": "-1.5",
          "Westgate": "-1.5",
          "SugarHouseNJ": "-1.5",
          "PointsBet": "-1.5",
          "WilliamHillNewJersey": "-1"
        },
        "over_under": {
          "MGM": "128.5",
          "DraftKings": "128.5",
          "FanDuel": "129",
          "Westgate": "128",
          "SugarHouseNJ": "131.5",
          "PointsBet": "128.5",
          "WilliamHillNewJersey": "128.5"
        }
      },
      "uuid": "96ca2381-196b-4e78-b5e5-f67614a0ad43",
      "neutralSite": true,
      "duration": null,
      "leadChanges": 6,
      "timesTied": 3,
      "clock": 0,
      "quarter": null,
      "clockDecimal": 0,
      "conferenceGame": false,
      "half": 3,
      "displayStatus": "closed"
    },
    "relationships": {
      "league": {
        "data": {
          "type": "League",
          "id": "\/basketball\/v2\/leagues\/da57437e-4688-4e1c-9bc5-6df2dcab1a14"
        }
      },
      "homeTeam": {
        "data": {
          "type": "Team",
          "id": "\/basketball\/v2\/teams\/686abcdc-e822-40fd-99b0-be1d17eff132"
        }
      },
      "awayTeam": {
        "data": {
          "type": "Team",
          "id": "\/basketball\/v2\/teams\/372f9f0d-ab05-43cd-8f81-f9d4921014ad"
        }
      },
      "nextEvent": {
        "data": {
          "type": "Event",
          "id": "\/basketball\/v2\/events\/e0814e64-ec98-4386-8dbb-68eb16643b26"
        }
      },
      "winloss": {
        "data": {
          "type": "WinLoss",
          "id": "\/basketball\/v2\/win_losses\/96ca2381-196b-4e78-b5e5-f67614a0ad43"
        }
      },
      "simulatedPicks": {
        "data": {
          "type": "Simulation",
          "id": "\/basketball\/v2\/simulations\/67ae8b41-157d-4d77-a2f0-ee32e8c2fe4c"
        }
      }
    }
  },
  "included": [
    {
      "id": "\/basketball\/v2\/win_losses\/96ca2381-196b-4e78-b5e5-f67614a0ad43",
      "type": "WinLoss",
      "attributes": {
        "detail": "The Radford Highlanders have a 71.6% chance of beating the North Carolina A\u0026T Aggies",
        "homeWinProbability": 72,
        "awayWinProbability": 28,
        "homeSpread": -6.80493,
        "awaySpread": 6.80493,
        "overUnder": 138.52,
        "winLossSpreadConsistency": 1,
        "overtimeProbability": null,
        "predictAsOvertime": null,
        "uuid": "96ca2381-196b-4e78-b5e5-f67614a0ad43",
        "probability": 72,
        "winnerUuid": "686abcdc-e822-40fd-99b0-be1d17eff132",
        "loserUuid": "372f9f0d-ab05-43cd-8f81-f9d4921014ad"
      },
      "relationships": {
        "event": {
          "data": {
            "type": "Event",
            "id": "\/basketball\/v2\/events\/96ca2381-196b-4e78-b5e5-f67614a0ad43"
          }
        }
      }
    },
    {
      "id": "\/basketball\/v2\/simulations\/67ae8b41-157d-4d77-a2f0-ee32e8c2fe4c",
      "type": "Simulation",
      "attributes": {
        "teamWinProbability": 100,
        "opponentWinProbability": 0,
        "uuid": "67ae8b41-157d-4d77-a2f0-ee32e8c2fe4c",
        "teamUUID": "372f9f0d-ab05-43cd-8f81-f9d4921014ad",
        "opponentUUID": "686abcdc-e822-40fd-99b0-be1d17eff132",
        "winnerUuid": "372f9f0d-ab05-43cd-8f81-f9d4921014ad",
        "loserUuid": "686abcdc-e822-40fd-99b0-be1d17eff132"
      },
      "relationships": {
        "winner": {
          "data": {
            "type": "Team",
            "id": "\/basketball\/v2\/teams\/372f9f0d-ab05-43cd-8f81-f9d4921014ad"
          }
        },
        "loser": {
          "data": {
            "type": "Team",
            "id": "\/basketball\/v2\/teams\/686abcdc-e822-40fd-99b0-be1d17eff132"
          }
        }
      }
    }
  ]
}

This gives you all the info you need for an event. Repeat for remaining events.

If the event is over, the data.attributes.homeTeamScore and data.attributes.awayTeamScore will be populated and data.attributes.displayStatus will be closed as in the above example.

The included array contains the included entities we asked for in the query (include=winloss,simulatedPicks) and are related to the data.relationships.winloss and data.relationships.simulatedPicks for the entity.

In this case

the WinLoss entity is the forecasted predictions for the event (win percents, spread, over/under, etc.) and only exists if both teams are known
the Simulation is the win/loss prediction for the tournament event when teams haven't been finalized yet

For future game in the tournament, the WinLoss will not exists until actual teams are known so you can use the Simulation to determine information about which teams we predict will be in the game event for that round when it occurs.

The simulated picks will update as the rounds progress and actual results are updated.

For more information on the relation mapping and JSON:API format see https://jsonapi.org