Skip to content

Player Effect API#

The following describes how to retrieve player effect predictions through the Quarter4 REST APIs.

Using the REST API to query for Player Effect Simulations#

Related APIS

Method Description Availability
POST /{sport}/v2/player_effects NFL

The player effect simulation api allows queries against the Quarter4 player effect models. These output player specific performance predictions based on the selected teams and players. By comparing results, performance impacts on a player level can be observed when adding and/or removing players from the active rosters.

When specifying players, changes can include:

  • setting the player's injury status,
  • removing players from the teams's roster,
  • adding players from another team to a roster (to simulate a trade for example).

Tip

To preview the results, check your O.D.D.S Dashboard > NFL > Predictions > Player Effect tools and look at the player effect after creating multiple matchups. See below for step-by-step usage of the dashboard tool.

To retrieve results by API, first, start by building a POST request body using two teams and the associated player modifications. The teams and players are identified by their Quarter4 UUIDs and each player must indicate an injury status of 0 for playing, or 1 for injured:

{
    "home": {
        "uuid": "4b678417-7135-456c-992b-f3dd64609894",
        "players": [
            {
                "uuid": "d634d84f-919e-4256-8a00-6668c4c08a91",
                "injured": 1
            },
            {
                "uuid": "eec23fc6-c316-4b9b-a8e3-5c970a634eb6",
                "injured": 0
            }
        ]
    },
    "away": {
        "uuid": "06248b76-a4ca-4f0c-9684-c60d929b89f6",
        "players": [
            {
                "uuid": "de5fd1c8-74d3-4f16-8e36-ee017e48588b",
                "injured": 1
            },
            {
                "uuid": "3b025e98-0eef-4a11-ac56-8460989ced54",
                "injured": 0
            },
            {
                "uuid": "7ffd5d34-8615-4f32-b39b-b026f8297cdd",
                "injured": 0
            }
        ]
    }
}

The body must have both a home and away element that reflect the two teams. The players attribute is the list of modification you would like to make to the existing roster.

Current roster and depth charts will be used to fill in the remaining players.

Warning

If a player is added from another team, an existing player in that team for the equivalent position must be removed to maintain the proper roster number. If the equivalent player is not removed, the resulting predictions and performance impacts may not be accurate.

Sending this body as a POST request to https://api.quarter4.io/american-football/v2/player_effects will return the individual player predictions for each player on each team. By running multiple requests with varying inputs you can build a comparison and impact across changes.

The response may take a bit of time depending on the number of players selected as the machine learning engine must process the simulated events to determine the proper predictions for the event.

Note

For the effect of injuries on a team's win/loss performance in a game, see the Injury Effect API.

Manually Running the Player Effect Simulator in the O.D.D.S. Dashboard#

Here is the basic process of manually creating Player Effect comparisons. Start by logging into your dashboard and navigating to the Player Effect page for your desired sport. Then:

1. Select a matchup.#

Select a matchup

Select the desired matchup for your simulation.

2. Run a baseline simulation#

Run a baseline simulation

To make modifications to any roster, an initial baseline simulation must be run.

3. Create the base simulation#

Create the base simulation

To run a new simulation with the same teams, click the symbol beside the simulation summary.

4. Alter Rosters#

Make alterations to the rosters to run a comparison:

Remove players from the roster#

Remove players from the roster

Toggle off each individual player to remove them from the simulation

Transfer Players#

Remove players from the roster

Select the drop down menu to search by team, or type the player’s name into the search bar. Drag and drop players into the desired team.

Swap Players#

Remove players from the roster

Drag a player’s headshot and drop into the opposing team’s roster to trade players between teams.

5. Adjust Players Limits#

Adjust Limits

When adding any player to a team, another player of the same position must be removed in order to run a simulation.

6. Run your new simulation!#

Run New Simulation

When satisfied with the rosters, run your simulation.

7. Compare#

Compare

To compare different simulation results, select compare and choose the desired simulation to compare. Select clear comparison to start a new comparison.

8. Reset#

Reset

To clear the simulation and start from scratch, select reset.You may also select new teams to clear the simulation.