players

Player stats for a season + league

Baseball responses carry a level field. Read it before summing anything.

  • level: "match": batting/pitching are totals folded from real per-game box scores. 2026 onward.
  • level: "season": no per-game box scores exist for the seasons asked for. The numbers are full-season aggregates and are returned in seasons[], each entry additionally marked level: "season". batting/pitching are null.
  • level: "mixed": both are present. batting/pitching (per-game derived) and seasons[] (season aggregates) cover disjoint periods; adding them together double-counts nothing but conflates two different grains. Treat them separately.

A season aggregate has no home/away dimension, so ?split=home|away returns no seasons[] entries rather than full-season totals that ignore the filter. Fields a source cannot supply (e.g. pitch counts, which season-level history does not carry) are omitted, never returned as 0.

get/v1/players/{id}/stats

Request

  • Base URL: https://api.bigballsdata.com
  • URL: https://api.bigballsdata.com/v1/players/{id}/stats
  • Auth: one of:
    • API key in header x-api-key
    • HTTP bearer

Path parameters

idstring uuid required

Query parameters

sport'football' | 'basketball' | 'baseball' | 'ice_hockey' | 'cricket' | 'mma' | 'boxing' | 'formula1' | 'american_football' required

Required: the players table has no sport column, so this can't yet be inferred from the id (unlike /v1/teams/{id} and /v1/matches/{id}).

seasonstring

Season LABEL, not a calendar year: the year a season STARTS in. 2025 means the 2025-26 campaign for leagues that cross the new year (EPL, NBA, NHL) and the 2025 season for those that do not (MLB, MLS, WNBA). Filtering resolves each league's own start month, so a season never spans two calendar years' worth of rows.

leaguestring

SCOPE, not a general filter, and the same shape as ?split= below. Read ONLY on the live-upstream branch (football, cricket, mma, boxing, formula1), where it is passed through as the vendor's league id. The DB-backed branches (basketball, american_football, baseball, ice_hockey) serve one aggregate per player per sport and IGNORE it: measured 2026-09-20, ?sport=basketball with league=nba, league=epl and no league returned the same 283-byte body (hash 3ebe3df427), while ?split= over its three values returned three distinct hashes as the control.

split'home' | 'away' | 'all'

Per-game splits (basketball + baseball). Season-level aggregates cannot be split and are omitted when this is set to home or away.

Response

ok. { data, meta }. data is POLYMORPHIC by sport and by what we hold; see the branches below. Declared no content at all until 2026-09-25.

Example response

{
  "meta": {
    "date_window": {
      "timezone": "UTC",
      "start_utc": "2026-09-13T00:00:00.000Z",
      "end_utc": "2026-09-14T00:00:00.000Z"
    },
    "source": "official-league",
    "confidence": 0.95,
    "cache_age_ms": 4200,
    "request_id": "req_abc123",
    "note": "match_id is omitted on 380 of 380 rows in this response. The live feed behind them does not carry an id we can resolve to a stored match, so we return no id rather than one that will not work. For rows with ids you can call back into, use /v1/stored/matches with the same sport or league, for example /v1/stored/matches?league=epl."
  },
  "error": {
    "code": "NOT_FOUND"
  }
}

Changes

No recorded changes to this operation across all 3 revisions of this API.