Skip to content

Daily Fantasy Sports Lineup Optimizer#

The DFS lineup optimizer API provides lineup optimization for FanDuel and DraftKings lineups.

Information can be updated roughly every 15 mins when a change is required. Please review our Building Your Application guide for general suggestions on data flow, caching and optimizing queries to our Spotr Data APIs.

API Key

The API key is a secret key associated with your account. Do not share it or expose it in public web pages. Doing so would allow anyone to make queries as if they were you. If you think your API key may have been compromised, contact your Account representative immediately to disable your current key and receive a new key.

Using the REST API to create optimized lineups#

Related Sports Data APIS

Method Description Availability
POST /{sport}/v2/fantasy/lineup-optimizer MLB, NBA, NFL, NHL

Request Attributes#

The following describes all the information required to query the lineup optimizer.

Entrypoint#

GET https://api.quarter4.io/{sport}/v2/fantasy/lineup-optimizer

Path Parameters#

  • sport currently only american-football is available as the sport and only NFL players are supported.

Query Parameters#

  • api_key Your api key available though the dashboard admin or ask your account representative.
  • include: JSON:API include parameter to include the related Player entities from the selections and defenseSpecialTeams. Note, the included entity attributes are filtered to DFS related values, For the full attributes unrelated to DFS you can also query the /{sport}/v2/players/{uuid} and /{sport}/v2/teams/{uuid} endpoints to retrieve the full entity.
  • count The number of lineups you'd like to receive between 1 and 5. Default is 3.

Common JSON Request POST Attributes#

See the example below for the specific format of each item.

  • book: Indicates which book rules should be applied. (one of draftkings or fanduel)
  • contest: Indicates the contest type rules should be applied. One of classic or showdown.
  • include: A list of teams and players must be included in the lineup. Each entry must contain a respective team or player UUID value along with an optional position. If the contest is showdown an item in include may also specify a position of CPT. See example for format below.
  • exclude: A list of team and player UUIDs for items that must be excluded in the lineup (this could also be achieved by not including them in the players and teams lists but the option is here for completeness). See example for format below.
  • players: A list of available players available for selection in the contest. Each entry must contain the player UUID, the player’s fantasy salary and the position they will play. If the contest is showdown then each entry in players must also include a captainSalary. See example for format below.
  • teams: A list of available teams available for selection in the contest. Each entry must contain the team UUID and the team’s fantasy salary. If the contest is showdown then each entry in teams must also include a captainSalary. See example for format below.
  • games: A list of available games included in the contest. Each entry must contain an event UUID. A classic contest requires at least two games, a showdown must specify only one.
  • cap: The target salary cap for the lineup. The sum of the salaries in the generated lineup will not go above this amount.
  • positions: The minimum number to pick for each position (see contest details elow for mor info).
  • count integer: The number of lineups you'd like to receive between 1 and 10. This takes precedence over the query variable of the same name.
  • stack boolean (default false): enables additional optimizer options:
  • If no players are included in the include field, the optimizer will stack at least 1 QB and 1 WR together.
  • If 1 QB is added in the include field the model will try to optimize AT LEAST 1 WR to match to the QB.
  • If 1 WR is added in the include field the model will try to optimize their QB to match to the WR.
  • If a QB AND WR are added in the include field the optimizer WILL NOT stack another WR because the stacking strategy has been fulfilled.

Response Attributes#

The following describes the expected response.

JSON:API Response Attributes#

See the example below for the specific format of each item.

  • links: link references to additional pages if any (this endpoint only returns a single result)
  • meta: additional meta info such as item count (always 1 for this endpoint)
  • data: The result of the response. For this endpoint, this will always be an array with one item.
    • id: the JSON:API id of the item.
    • type: the JSON:API entity type
    • attributes: entity attributes
      • salaryCap: Value of cap from the request.
      • salaryRemaining: The remaining unused salary.
      • salaryTotal: The sum of the salaries used by the picks.
      • book: Value of book from the request.
      • contest: Value of contest from the request.
      • points: the sum of the points in the lineup.
      • byPosition: Grouping of the players in selection by position. DST is the defenseSpecialTeams team. The related player and team info can be found in the included section of the response when using include=selections,defenseSpecialTeams in the query.
      • uuid: The UUID of the lineup response. This can be used with support issues if you supply the support team with the UUID of the response.
      • updatedAt: when the response was generated.
    • relationships: Related entities. These entries only include the JSON:API identifier information. For the full details use “include=” in the query along with the group you would like to include. In that case, an included section is added to the response containing the included entries. You can use the id or uuid to match each item in the entity to the entities in the included section.
      • mustExclude**: items supplied in the requestexclude` query variables.
      • selections**: The players selected for the lineup. The items in the responseincluded` attribute indicates the salaries, position, and points.
      • defenseSpecialTeams: the team selected for DST.
      • mustInclude: items supplied in the request include query variables.
    • included: a list of additional entities from the relationships. The example below shows the Player and Team entities included in the example response. Of note, along with additional attributes such as name, each entry includes a dfsSalary, dfsPosition, and dfsPoints for the lineup related details. This info is similar to what is found in the byPosition attribute of the FantasyLineup entity.

League Specific Contest Details#

NFL#

NFL COntest Parameters#
  • DraftKings Classic
  • 9 players and must include players from at least 2 different games

  • The minimum positions definition typically looks like:

    • QB: 1
    • RB: 2
    • WR: 3
    • TE: 1
    • FLEX: 1 (RB, WR, TE)
    • DST: 1

  • DraftKings Showdown

  • 6 players and must include players from both teams

  • The minimum positions definition typically looks like:

    • FLEX: 5 (QB, WR, RB, TE, K, DST)
    • CPT: 1 (QB, WR, RB, TE, K, DST)

  • FanDuel Classic

  • 9 players and must include players from at least 2 different games
  • The minimum positions definition typically looks like:
    • QB: 1
    • RB: 2
    • WR: 3
    • TE: 1
    • FLEX: 1 (RB, WR, TE)
    • DST: 1
NFL Rules and Scoring#
  • DraftKings
  • Offense:
    • passing touchdowns: 4
    • passing yards: 0.04
    • passing yards 300plus: 3
    • passing interceptions: -1
    • rushing touchdowns: 6
    • rushing yards: 0.1
    • rushing yards 100plus: 3
    • receiving touchdowns: 6
    • receiving yards: 0.1
    • receiving yards 100plus: 3
    • receiving receptions: 1
    • punt returns touchdowns: 6
    • kick returns touchdowns: 6
    • fumbles lost fumbles: -1
    • extra points conversions receive successes: 2
    • extra points conversions rush successes: 2
    • extra points conversions pass successes: 2
    • statistics fumbles own rec tds: 6
    • extra points kicks made: 1
    • field goals made39: 3
    • field goals made49: 4
    • field goals made50: 5
  • Defense
    • defense sacks: 1
    • defense interceptions: 2
    • defense fumble recoveries: 2
    • touchdowns total return: 6
    • defense safeties: 2
    • defense sp blocks: 2
    • extra points defense conversions: 2
    • defense points allowed: 1
  • FanDuel:
  • Offense:
    • passing touchdowns: 4
    • passing yards: 0.04
    • passing interceptions: -1
    • rushing touchdowns: 6
    • rushing yards: 0.1
    • receiving touchdowns: 6
    • receiving yards: 0.1
    • receiving receptions: 0.5
    • punt returns touchdowns: 6
    • kick returns touchdowns: 6
    • fumbles lost fumbles: -2
    • extra points conversions receive successes: 2
    • extra points conversions rush successes: 2
    • extra points conversions pass successes: 2
    • statistics fumbles own rec tds: 6
    • extra points kicks made: 1
    • field goals made39: 3
    • field goals made49: 4
    • field goals made50: 5
  • Defense:
    • defense sacks: 1
    • defense interceptions: 2
    • defense fumble recoveries: 2
    • touchdowns total return: 6
    • defense safeties: 2
    • defense sp blocks: 2
    • extra points defense conversions: 2
    • defense points allowed: 1

NHL#

The NHL optimizer supports the following contests:

NHL Contest Parameters#
  • DraftKings Classic
  • 8 Players, Selections must be from at least 3 teams

  • The minimum positions definition typically looks like:

    • C: 2
    • W: 3
    • D: 2
    • UTIL: 1 (Any other skater)
    • G: 1

  • DraftKings Showdown

  • 6 Players, Selections are from a single game, must involve players from both teams

  • The minimum positions definition typically looks like:

    • UTIL: 5 (Any position, including G)
    • CPT: 1 (Any position, including G)

  • FanDuel Classic

  • 8 Players, Selections can't have more than 4 players on 1 team
  • The minimum positions definition typically looks like:
    • C': 2
    • W': 2
    • D': 2
    • UTIL: 2 (Any other skater)
    • G': 1
NHL Rules and Scoring#

The optimizer uses the following rules and scoring settings:

  • DraftKings:
  • Skaters
    • goals: 8.5
    • assists: 5
    • shots_on_goal: 1.5
    • blocked_shots: 1.3
    • short_handed_points: 2
    • shootout_goals: 1.5
    • hat_trick_bonus: 3
    • 5plus_shots: 3
    • 3plus_blocked_shots: 3
    • 3plus_points: 3
    • Goalies:
    • win: 6
    • saves: 0.7
    • goals_against: -3.5
    • shutout: 4
    • overtime_loss: 2
    • 35plus_saves: 3
    • FanDuel:
    • Skaters:
    • goals: 12
    • assists: 8
    • shots_on_goal: 1.6
    • power_play_bonus: 0.5
    • short_handed_bonus: 2
    • blocked_shots: 1.6
  • Goalies
    • win: 12
    • saves: 0.8
    • goals against: -4
    • shutout: 8

NBA#

NBA Contest Parameters#
  • DraftKings Classic
  • 8 Players, Selections must be from at least 2 games
  • The minimum positions definition typically looks like:
    • PG: 1
    • SG: 1
    • SF: 1
    • PF: 1
    • C: 1
    • G: 1 (PG SG)
    • F: 1 (SF PF)
    • UTIL: 1 (PG SG SF PF C)
  • DraftKings Showdown
  • 6 Players, Selections are from a single game, must involve players from both teams
  • The minimum positions definition typically looks like:
    • UTIL: 5 (Any position)
    • CPT: 1 (Any position)
  • FanDuel Classic
  • 9 Players, Selections can't have more than 4 players on 1 team -> equivalent 3 teams
  • The minimum positions definition typically looks like:
    • PG: 2
    • SG: 2
    • SF: 2
    • PF: 2
    • C: 1
NHL Rules and Scoring#

The optimizer uses the following rules and scoring settings:

  • DraftKings:
  • point: 1, 3pt = 3, 2pt = 2, FT = 1
  • 3pt bonus: 0.5 (extra bonus for making a 3pt shot)
  • rebound: 1.25
  • assist: 1.5
  • steal: 2
  • block: 2
  • turnover: -0.5
  • double-double: 1.5 (max 1 per player)
  • triple-double: 3 (max 1 per player)
  • FanDuel:
  • point: 1, 3pt = 3, 2pt = 2, FT = 1
  • rebound: 1.2
  • assist: 1.5
  • block: 3,
  • steal: 3,
  • turnover: -1

Example#

The following is an example of what a typical request/response would look like. You will need to include your api_key in the query examples.

JSON Request#

The following example is for an NFL DraftKings Classic contest and uses cURL via command line but you can use any HTTPS compatible connection libraries for your programming language of choice. You’ll also be required to append &api_key=YOUR_API_KEY to the url to authorize with the API.

curl -X "POST" "https://api.quarter4.io/american-football/v2/fantasy/lineup-optimizer?include=selections,defenseSpecialTeams" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "book": "draftkings",
  "contest": "classic",
  "include": {
    "players": [
      {
        "player":"72179a19-af54-464a-94cf-25a914f6dfd8"
      }
    ],
    "teams": [
      {
        "team":"da067403-25e8-4f40-a02e-55cda46f0b6b"
      }
    ]
  },
  "exclude": {
    "players": [
      "dc8c9dfe-f4fa-4608-b4ff-b7554407ec0a"
    ],
    "teams": [
      "cfd747f4-6b21-4896-b65a-b90787522092"
    ]
  },
  "players": [
    {
      "player": "72179a19-af54-464a-94cf-25a914f6dfd8",
      "salary": 3400,
      "captainSalary": 6800, 
      "position": "QB"
    },
    ...etc...
  ],
  "teams": [
    {
      "team": "da067403-25e8-4f40-a02e-55cda46f0b6b",
      "salary": 2095,
      "captainSalary": 4190, 
    },
    ...etc...
  ],
  "cap": 50000,
  "positions": {
    "RB": 2,
    "WR": 3,
    "QB": 1,
    "TE": 1,
    "DST": 1,
    "FLEX": 1
  },
  "games": [
    "b1f11cd3-23ff-446b-9973-38bbf430f663",
    "572e5aeb-b8dd-49f5-bc6a-1153afad8136"
  ]
}

JSON:API Response#

The following is an example API response, truncated for brevity.

{
  "links": {
    "self": "\/american-football\/v2\/fantasy\/lineup-optimizer?include=selections%2CdefenseSpecialTeams"
  },
  "meta": {
    "totalItems": 1
  },
  "data": [
    {
      "id": "\/american-football\/v2\/fantasy_lineups\/4205cd9d-bc07-4323-88a6-fc5733d12ff1",
      "type": "FantasyLineup",
      "attributes": {
        "salaryCap": 50000,
        "salaryRemaining": 49898,
        "book": "draftkings",
        "contest": "classic",
        "points": 63,
        "byPositions": {
          "QB": [
            {
              "uuid": "f2092bcb-f75d-4c16-916f-3e3f6f1c1e62",
              "points": 12.4895
            }
          ],
          "RB": [
            {
              "uuid": "1a535531-a05b-4811-b9d4-9e87e7301e54",
              "points": 16.064
            },
            {
              "uuid": "e3ea30f4-6ecf-48b3-9817-4788b1ec5252",
              "points": 11.5908
            }
          ],
          "WR": [
            {
              "uuid": "399ef2d2-db91-4d8a-8478-64e4c6875f63",
              "points": 16.5912
            },
            {
              "uuid": "fda69489-1404-49d9-a0de-d82de9290a42",
              "points": 3.22086
            },
            {
              "uuid": "7a14ecc2-d822-4741-aa32-c009fcc8f1d4",
              "points": 5.64456
            }
          ],
          "TE": [
            {
              "uuid": "b9918005-a78c-4511-8a9f-1cebccd7aaae",
              "points": 7.409
            }
          ],
          "FLEX": [
            {
              "uuid": "5bc42db4-b594-4e9b-852b-16d61c3ebab9",
              "points": 8.34819
            }
          ],
          "DST": [
            {
              "uuid": "a2465bfe-e4b5-4f67-bd02-55f727eeb348",
              "points": 7.0998
            }
          ]
        },
        "uuid": "4205cd9d-bc07-4323-88a6-fc5733d12ff1",
        "updatedAt": "2023-07-18T15:22:49+00:00"
      },
      "relationships": {
        "mustInclude": {
          "data": [
            {
              "type": "Player",
              "id": "\/american-football\/v2\/players\/72179a19-af54-464a-94cf-25a914f6dfd8"
            },
            ...etc...

          ]
        },
        "mustExclude": {
          "data": [
            {
              "type": "Player",
              "id": "\/american-football\/v2\/players\/dc8c9dfe-f4fa-4608-b4ff-b7554407ec0a"
            },
            ...etc...

          ]
        },
        "selections": {
          "data": [
            {
              "type": "Player",
              "id": "\/american-football\/v2\/players\/72179a19-af54-464a-94cf-25a914f6dfd8"
            },
            ...etc...
          ]
        },
        "defenseSpecialTeams": {
          "data": {
            "type": "Team",
            "id": "\/american-football\/v2\/teams\/da067403-25e8-4f40-a02e-55cda46f0b6b"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "\/american-football\/v2\/players\/72179a19-af54-464a-94cf-25a914f6dfd8",
      "type": "Player",
      "attributes": {
        "firstName": "Anthony",
        "lastName": "Richardson",
        "fullName": "Anthony Richardson",
        "uniform": "5",
        "dfsSalary": 56,
        "dfsPosition": "RB",
        "dfsPoints": 27,
        "uuid": "72179a19-af54-464a-94cf-25a914f6dfd8",
        "updatedAt": "2023-06-23T08:17:29+00:00"
      },
      "relationships": {
        "league": {
          "data": {
            "type": "League",
            "id": "\/american-football\/v2\/leagues\/38344248-9889-11eb-a8ab-0647cdb505d0"
          }
        }
      }
    },
    ...etc...
  ]
}