NflPlayerWeekStat

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bigballsdata-com/json-schema/bigballsdata-com-nfl-player-week-stat-schema.json",
  "title": "NflPlayerWeekStat",
  "description": "One player's stat line for one game-week. All stat fields are returned\nfor every row regardless of position: a quarterback row carries 0 or\nnull in the defensive columns, a linebacker row carries 0 or null in\nthe passing columns.\n\nDefensive columns come from the same weekly player data as the\noffensive ones and cover 2020 onward at the same grain.\n\n**TACKLE TOTALS WILL NOT MATCH `/v1/stored/matches/{id}/stats`, and that\nis expected.** This dataset carries three tackle counts and no combined\ntotal: `tackles_solo`, `tackle_assists` (assisted tackles the player\ntook part in) and `tackles_with_assist` (a much smaller, separate\ncount). The other endpoint serves a single `totalTackles` from a\ndifferent provider, at per-match rather than per-game-week grain, over\na different set of seasons.\n\nWe do NOT derive a combined total here. The usual definition is solo +\nassisted, but the exact relationship between these three counts\nwas not verified against a reference box score, and a plausible number\ncomputed from an unverified relationship is worse than no number; it\nis indistinguishable from a correct one. Add `tackles_solo` and\n`tackle_assists` yourself if you need a total, knowing that is your\ndefinition rather than ours.\n",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/bigballsdata-com-api-openapi.json#/components/schemas/NflPlayerWeekStat",
  "type": "object",
  "properties": {
    "as_of": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Stored value-change timestamp for this weekly row; null when unknown, never the request time."
    },
    "player_id": {
      "type": "string",
      "description": "NFL player id (gsis format)."
    },
    "player_name": {
      "type": [
        "string",
        "null"
      ]
    },
    "team": {
      "type": [
        "string",
        "null"
      ],
      "description": "Team abbreviation the player suited up for that week."
    },
    "season": {
      "type": "integer",
      "description": "Season LABEL: the year the season starts in."
    },
    "week": {
      "type": "integer"
    },
    "season_type": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "REG",
        "POST",
        "PRE"
      ]
    },
    "position": {
      "type": [
        "string",
        "null"
      ]
    },
    "passing_yards": {
      "type": [
        "integer",
        "null"
      ]
    },
    "passing_tds": {
      "type": [
        "integer",
        "null"
      ]
    },
    "completions": {
      "type": [
        "integer",
        "null"
      ]
    },
    "attempts": {
      "type": [
        "integer",
        "null"
      ]
    },
    "rushing_yards": {
      "type": [
        "integer",
        "null"
      ]
    },
    "rushing_tds": {
      "type": [
        "integer",
        "null"
      ]
    },
    "carries": {
      "type": [
        "integer",
        "null"
      ]
    },
    "receiving_yards": {
      "type": [
        "integer",
        "null"
      ]
    },
    "receiving_tds": {
      "type": [
        "integer",
        "null"
      ]
    },
    "receptions": {
      "type": [
        "integer",
        "null"
      ]
    },
    "targets": {
      "type": [
        "integer",
        "null"
      ]
    },
    "fantasy_points_ppr": {
      "type": [
        "number",
        "null"
      ],
      "description": "Standard PPR: 1/reception, 0.1/rush-rec yard, 0.04/pass yard, 6/TD, -2/int or fumble lost."
    },
    "interceptions": {
      "type": [
        "integer",
        "null"
      ],
      "deprecated": true,
      "description": "DEPRECATED and ALWAYS NULL. The loader read a column the dataset\ndoes not carry, so this was never written in any of 112,333 rows. The\nkey is retained only so existing clients do not break. Read\n`interceptions_thrown` or `interceptions_caught`, which say which\none they mean.\n"
    },
    "interceptions_thrown": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Interceptions thrown by this player (the quarterback turnover stat)."
    },
    "interceptions_caught": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Interceptions caught by this player (the defensive takeaway stat)."
    },
    "tackles_solo": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Unassisted tackles. Not a combined total; see the schema description before comparing against totalTackles elsewhere."
    },
    "tackle_assists": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Assisted tackles this player participated in. Not interchangeable with tackles_with_assist."
    },
    "tackles_with_assist": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Tackles made WITH an assist from a team-mate. A much smaller count than tackle_assists."
    },
    "tackles_for_loss": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Tackles made behind the line of scrimmage."
    },
    "tackles_for_loss_yards": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Yards lost by the offence on those tackles."
    },
    "sacks": {
      "type": [
        "number",
        "null"
      ],
      "description": "Sacks credited. FRACTIONAL; a shared sack is credited as 0.5 to each defender."
    },
    "sack_yards": {
      "type": [
        "number",
        "null"
      ],
      "description": "Yards lost on this player's sacks. Fractional for the same half-credit reason as sacks."
    },
    "qb_hits": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Hits on the quarterback",
      "sacks excluded.": null
    },
    "passes_defended": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Passes broken up without intercepting."
    },
    "fumbles_forced": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Fumbles forced. Forcing is not recovering; recoveries are not currently served."
    },
    "interception_yards": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Return yards on this player's interceptions. MAY BE NEGATIVE; a return can be tackled behind the catch point."
    },
    "defensive_tds": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Touchdowns scored on defence. Distinct from passing_tds / rushing_tds / receiving_tds on the same row."
    },
    "safeties": {
      "type": [
        "integer",
        "null"
      ]
    },
    "punt_blocks": {
      "type": [
        "integer",
        "null"
      ]
    },
    "pat_blocks": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Extra-point attempts blocked."
    },
    "fg_blocks": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Field-goal attempts blocked."
    },
    "defensive_two_point_attempts": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Two-point conversion returns attempted by the defence."
    },
    "defensive_two_point_conversions": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Two-point conversion returns scored by the defence."
    },
    "times_sacked": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Times this OFFENSIVE player (almost always a QB) was sacked. Distinct from `sacks` above, which is the DEFENSIVE credit."
    },
    "sack_yards_lost": {
      "type": [
        "number",
        "null"
      ],
      "description": "Yards lost on this player's own sacks. Distinct from `sack_yards` above, which is the DEFENSIVE figure."
    },
    "passing_air_yards": {
      "type": [
        "number",
        "null"
      ],
      "description": "Weekly sum of air yards on this player's pass attempts. Per-play value on GET /v1/nfl/games/{id}/plays as `air_yards`."
    },
    "passing_yards_after_catch": {
      "type": [
        "number",
        "null"
      ],
      "description": "Weekly sum of yards after the catch on this player's completions. Unofficial figure."
    },
    "passing_first_downs": {
      "type": [
        "integer",
        "null"
      ]
    },
    "passing_epa": {
      "type": [
        "number",
        "null"
      ],
      "description": "Total EPA on this player's pass attempts and sacks."
    },
    "passing_2pt_conversions": {
      "type": [
        "integer",
        "null"
      ]
    },
    "dakota": {
      "type": [
        "number",
        "null"
      ],
      "description": "Adjusted EPA + CPOE composite. A published advanced metric, not derived by us."
    },
    "rushing_first_downs": {
      "type": [
        "integer",
        "null"
      ]
    },
    "rushing_epa": {
      "type": [
        "number",
        "null"
      ]
    },
    "rushing_2pt_conversions": {
      "type": [
        "integer",
        "null"
      ]
    },
    "receiving_air_yards": {
      "type": [
        "number",
        "null"
      ],
      "description": "Weekly sum of air yards on targets to this player. Per-play value on GET /v1/nfl/games/{id}/plays as `air_yards`."
    },
    "receiving_yards_after_catch": {
      "type": [
        "number",
        "null"
      ],
      "description": "Weekly sum of yards after the catch by this receiver. Per-play value on GET /v1/nfl/games/{id}/plays as `yards_after_catch`."
    },
    "receiving_2pt_conversions": {
      "type": [
        "integer",
        "null"
      ]
    },
    "fantasy_points": {
      "type": [
        "number",
        "null"
      ],
      "description": "Standard (non-PPR) fantasy total. See fantasy_points_ppr for the PPR total."
    },
    "air_yards_share": {
      "type": [
        "number",
        "null"
      ],
      "description": "This player's share of the team's air yards this game-week. Fraction in [0,1]."
    },
    "pacr": {
      "type": [
        "number",
        "null"
      ],
      "description": "Passing (yards) Air (yards) Conversion Ratio. A published advanced metric, not derived by us."
    },
    "racr": {
      "type": [
        "number",
        "null"
      ],
      "description": "Receiving (yards) Air (yards) Conversion Ratio. A published advanced metric, not derived by us."
    },
    "receiving_epa": {
      "type": [
        "number",
        "null"
      ]
    },
    "receiving_first_downs": {
      "type": [
        "integer",
        "null"
      ]
    },
    "special_teams_tds": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Kick/punt return touchdowns. Distinct from defensive_tds and the offensive *_tds columns."
    },
    "wopr": {
      "type": [
        "number",
        "null"
      ],
      "description": "Weighted Opportunity Rating: 1.5 x target_share + 0.7 x air_yards_share. A published advanced metric, not derived by us."
    },
    "target_share": {
      "type": [
        "number",
        "null"
      ],
      "description": "This player's share of the team's receiving targets this game-week. Fraction in [0,1]."
    }
  }
}