---
title: "NBA per-player projections for games later in the week"
method: GET
path: "/v1/predictions/nba/players/week"
tags: ["predictions"]
---

# NBA per-player projections for games later in the week

`GET /v1/predictions/nba/players/week`

## Request

- Base URL: `https://api.predixsport.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.predixsport.com/v1/predictions/nba/players/week`
- Auth: none declared

Lineup-free NBA player projections for scheduled games that have not been played, the look-ahead companion to the per-match endpoint. The same models run without a published starting five, so ``projection_mode`` is always ``calendar`` and ``started`` is always null.

AN EMPTY LIST IS THE NORMAL STATE, not an outage. NBA predictions are gated on the expected starting five, so the per-match surface exists only on game day, and this one exists only once the rest-of-week mode has run for the current batch.

TWO VIEWS OF THE SAME BATCH. ``players`` is one row per player per scheduled game. ``totals`` is one row per player for the WHOLE window, best first: games scheduled, the days they fall on, the projected points over the week and, with a ``preset``, that league's projected score for the week and the same number per game. ``totals`` is what a week planner reads, and it is built over every row that matches the filters rather than over the ``limit`` page of ``players``. Pass ``include_rows=false`` to get it on its own.

THE WEEK IS AN EXPECTATION AND NOTHING ELSE. A weekly number is the sum of the per-game expectations, exact for the mean by linearity, but a sum of dependent counts is not the convolution of the marginals, so no band, no distribution and no probability is published for it. There is no availability field here either, by design: days ahead of a game no lineup exists.

Use it to plan which players to pick up for the days ahead, then call the per-match endpoint on game day for the projection that knows the published five.

## Query parameters

- `player` string, nullable: Exact stored player name, e.g. 'Nikola Jokic'.
- `names` string, nullable: A whole roster at once: player names separated by commas, semicolons or newlines. Matching ignores case and accents (doncic finds Luka Dončić) and accepts a surname on its own or a surname with a first-name prefix (L. James). A name that matches nobody, or more than one player, is NOT guessed at: it comes back in ``unresolved_names`` while the rest are resolved. Use it instead of one request per player.
- `team` string, nullable: Exact stored franchise name, e.g. 'Denver Nuggets'.
- `court` string, nullable: Half of the floor: ``BC`` backcourt (guards) or ``FC`` frontcourt (forwards and centres). Formats that require a backcourt / frontcourt split filter on it.
- `limit` integer: Maximum rows in ``players`` AND maximum players in ``totals``, applied to each independently.
- `include_rows` boolean: Set false to omit the per-game ``players`` array and receive the per-player ``totals`` alone, which is the smaller answer and the one a week planner needs.
- `preset` 'espn_points' | 'yahoo_9cat' | 'sleeper_points' | 'nba_salary_cap'

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- NBAPlayerWeekResponse: Calendar-weighted NBA player projections for the days ahead. These rows are the lineup-free mode: the same models run without a published starting five, for games that have not been played. They are deliberately NOT part of the per-match endpoint, which describes the day's slate only. An empty list is a normal state, not an outage. NBA predictions are gated on the expected starting five, so the per-match surface exists only on game day, and this look-ahead surface exists only once the rest-of-week projection mode has run for the current slate.
  - `as_of` string, nullable: The projection batch these rows come from, as YYYYMMDD. Null when no rows exist yet.
  - `count` integer, required
  - `players` NBAPlayerCalendarProjection[]
    - `name` string, required
    - `team` string, required
    - `is_home` boolean, required
    - `position` integer, nullable: Rank slot inside the published starting five, 1 to 5, and 0 for a roster player outside it or for a projection made with no published lineup. It is NOT a listed basketball position: read ``listed_position`` and ``court`` for that.
    - `expected_points` number, nullable
    - `expected_rebounds` number, nullable
    - `expected_assists` number, nullable
    - `expected_three_pointers_made` number, nullable: Expected three-pointers made.
    - `points_distribution` object, nullable
    - `rebounds_distribution` object, nullable
    - `assists_distribution` object, nullable
    - `three_pointers_made_distribution` object, nullable
    - `expected_steals` number, nullable
    - `steals_distribution` object, nullable
    - `expected_blocks` number, nullable
    - `blocks_distribution` object, nullable
    - `expected_turnovers` number, nullable
    - `turnovers_distribution` object, nullable
    - `expected_field_goals_made` number, nullable
    - `field_goals_made_distribution` object, nullable
    - `expected_field_goals_attempted` number, nullable
    - `field_goals_attempted_distribution` object, nullable
    - `expected_free_throws_made` number, nullable
    - `free_throws_made_distribution` object, nullable
    - `expected_free_throws_attempted` number, nullable
    - `free_throws_attempted_distribution` object, nullable
    - `expected_nba_salary_cap_points` number, nullable: Expected NBA Salary Cap fantasy score (points + rebounds + 2 x assists + 3 x blocks + 3 x steals) from a model trained on that total directly, not from summing the component models. It is the only projected total with a distribution of its own.
    - `nba_salary_cap_points_distribution` object, nullable
    - `started` boolean, nullable: True when the player is in the team's published starting five for this game, false when a lineup was published and he is not in it, null when no lineup had been published at projection time. Null is a real state here, not a missing value. This is the published lineup and nothing more: it is not a chance of playing and carries no injury information.
    - `projection_mode` string, nullable: gameday (a lineup was published), gameday_no_lineup (the whole roster projected without one) or calendar (a lineup-free projection for a game later in the week). Null for rows written before the full-roster rollout.
    - `row_source` string, nullable: Where the roster row came from: box_score, roster_union or published_lineup.
    - `low_confidence` boolean, nullable: True when this row rests on a thin recent record, typically a roster player with no recent appearance. The row is published flagged rather than dropped.
    - `listed_position` string, nullable: Listed basketball position, e.g. PG, SG, SF, PF, C, G-F.
    - `court` string, nullable: BC for backcourt or FC for frontcourt, derived from the first token of listed_position. Fantasy formats that require a backcourt and frontcourt split use it.
    - `fantasy` NBAFantasyScore: Projected fantasy score for the requested scoring preset.
      - `preset` string, required
      - `label` string, required
      - `expectation` number, nullable: The projected score for this preset. For nba_salary_cap it is the model trained on that total itself, which is the number every Predixsport surface prints and ranks by. For every other points preset it is the preset's scoring formula applied to the component projections, exact for the average by linearity whatever the dependence between the individual stats. Null when any stat the formula needs is missing for this player: a partial total would understate him with nothing here to say so. Always null for yahoo_9cat, which is a per-category league with no single score.
      - `expectation_source` string: Which of the two readings ``expectation`` holds: ``direct_model`` for a preset scored by a model trained on its own total (nba_salary_cap), ``component_formula`` for the linear combination of the component projections, ``none`` when no score could be formed.
      - `formula_expectation` number, nullable: The preset formula applied to the component projections, published alongside ``expectation`` for nba_salary_cap so the two readings of the same total can be compared. It is a cross-check, not a second score: the served number is ``expectation``. Null for every other preset, where the two would be the same value.
      - `distribution_quantiles` object, nullable: Quantiles p10/p25/p50/p75/p90 of the score. Present for nba_salary_cap only, because it is the one preset with a model trained on the total itself. No composite distribution is claimed for the others: a sum of dependent counts is not the convolution of the marginals.
      - `categories` NBAFantasyCategory[], nullable: Per-category values. Present for yahoo_9cat only.
        - `key` string, required
        - `label` string, required
        - `value` number, nullable
        - `lower_is_better` boolean
        - `ratio_of_means` boolean: True for FG% and FT%, which are the ratio of two projected averages rather than a projected percentage. The distinction matters: the expected ratio is not the ratio of expectations.
    - `match_id` string, required: Identifier of the scheduled game, the usual file_name.
    - `date` string, date, required: Date the game is scheduled for.
  - `totals` NBAPlayerWeekTotal[]: One row per player for the whole window, best first: the ranked view a week planner reads. It is computed over every row that matches the filters, not only the ones returned in ``players``, and is capped by ``limit`` in its own right. Set ``include_rows=false`` to receive this block alone.
    - `player_name` string, required
    - `team` string, nullable
    - `court` string, nullable: BC for backcourt or FC for frontcourt.
    - `listed_position` string, nullable
    - `games_this_week` integer, required: Scheduled games for this player inside the batch.
    - `dates` string[]: The days those games fall on.
    - `low_confidence` boolean, nullable: True when at least one of the player's rows rests on a thin recent record.
    - `expected_points` number, nullable: Projected points over the whole week. Points is one of the five heads that cleared the single-number gate, so it is safe to read as a number; it is also what a category league can rank by, having no single score of its own.
    - `expectation` number, nullable: The week's projected score under the requested preset, summed over the player's scheduled games. Null without a preset, for yahoo_9cat, which has no single score, and when a component the formula needs is missing on any one of his games.
    - `expectation_per_game` number, nullable: ``expectation`` divided by ``games_this_week``: the same total read as a rate, which separates a busy calendar from a strong player.
    - `expectation_source` string: Which reading ``expectation`` holds: ``direct_model`` for nba_salary_cap, whose head is trained on the total itself, ``component_formula`` for the rest, ``none`` when no score could be formed.
    - `form_blend` number, nullable: REALISED form, the only backward-looking number here: the mean of the player's season-to-date average and his last-five average of actual fantasy points under the requested preset, with games he did not play counted as zero. It is the ranking key of the captain rule Predixsport recommends, which has no model in it: back your best form player on the first day he is in his team's published five. Null when the player has no reconciled games yet, and for a category preset it is measured in NBA Salary Cap points, which is the only total a category league can borrow.
  - `dates` string[]: Every day covered by the batch, ascending.
  - `resolved_names` string[]: Stored names the ``names`` parameter matched, in the order they were written. Empty when the parameter was not used.
  - `unresolved_names` string[]: Entries of ``names`` that matched no player, or matched more than one and were therefore not guessed at. Echoed back so a pasted roster can be corrected rather than silently short.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/predixsport/apis/predixsport-api.md) · [All operations](https://skmtc.dev/predixsport/apis/predixsport-api/llms.txt) · [OpenAPI document](https://skmtc.dev/predixsport/apis/predixsport-api/revisions/02014aee733d?raw)