STAT-API

NBA players API

playersnba.players
Every individual who has played in the NBA — current rosters, two-way and 10-day contracts, G-League call-ups, free agents, and retired veterans. The roster signal lives in `roster_status` (the canonical cross-league vocabulary) and `team_id` (null for free agents and retired players). Pass `?team_id=` to scope to one franchise's current roster, or omit it to scan the full historical roster pool.
Full field reference (40 columns) → Data DictionaryQuery in GraphQL →
GET/api/v1/nba/players
Requires one of: roster_status — requests satisfying none of these return 400.
Parameters
team_idquerybigintoptional
Filter to players whose current team_id matches. Null team_id rows (free agents, retired) are excluded when this filter is applied.
roster_statusquerystringoptional
Filter by canonical roster status. Defaults to active (current roster); pass roster_status= explicitly for other tiers (injured_reserve, free_agent, retired, inactive). The "on a team now" set is {active, injured_reserve}. Values: active, injured_reserve, free_agent, retired, inactive.
limitqueryintegeroptionaldefault 100
Page size. Defaults to 100; max 5000.
from_idquerybigintoptional
Return rows with id strictly greater than this value; page using the previous response's `next_from_id`. Omit on the first page.
Restores the documented defaults (trial keys only accept the unchanged defaults).
Request
curl -sS --compressed \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  'https://api.stat-api.com/api/v1/nba/players?roster_status=example'
Responses
200players rows matching the declared filter set, wrapped in { players, limit, next_from_id }. next_from_id is the last row's id on a full page — pass it back via ?from_id= to walk the full result; null marks the terminal page.application/jsonshow example ▸
400No declared filter set was satisfied — response body matches MissingRequiredFiltersError; pick one combo from the accepted-sets hint and resend.application/json
Response Schema(40 fields)show schema ▸
FieldTypeReferencesDescription
idkey
bigint—Primary Key
league_player_id
integer—Official NBA player ID (issued by the league). Stable across seasons; use it to join other data that carries the league id.
e.g. 203999
team_id
bigintnullableFK to nba.teams. Null for free agents and retired players.
e.g. 12
birth_city
stringnullable—City of birth.
e.g. Sombor
birth_country
stringnullable—Country of birth (ISO English name).
e.g. Serbia
birth_date
datenullable—Birth date in YYYY-MM-DD form.
e.g. 1995-02-19
birth_state
stringnullable—State / province of birth (US/Canadian players).
e.g.
display_fi_last
stringnullable—Display name in "F. Last" form.
e.g. N. Jokić
display_last_comma_first
stringnullable—Display name in "Last, First" form. Useful for sorted lists.
e.g. Jokić, Nikola
dleague_flag
stringnullable—Two-character bit-string from the league: "00" no G-League history, "01" G-League experience, "11" currently G-League-affiliated (two-way / assignment).
e.g. 00
draft_number
stringnullable—Overall pick number within the draft (string). Empty for undrafted.
e.g. 41
draft_round
stringnullable—Draft round (string). Empty for undrafted players.
e.g. 2
draft_year
stringnullable—Year the player was drafted (string form). Empty for undrafted players.
e.g. 2014
experience
integernullable—Years of NBA experience as of the most recent season. Rookies = 0.
e.g. 10
first_name
string—Player's legal first name as registered with the league.
e.g. Nikola
from_year
stringnullable—Player's NBA debut year as a string (as the league records it).
e.g. 2015
full_name
string—Convenience concatenation of first_name + last_name. Use this for display.
e.g. Nikola Jokić
full_position_list
stringnullable—Hyphenated full-word position list (e.g., "Guard-Forward", "Center-Forward").
Values:GuardForwardCenterGuard-ForwardForward-CenterCenter-ForwardForward-Guard
games_played_flag
stringnullable—String "Y"/"N" indicating whether the player has played at least one regular-season game.
Values:YN
height
integernullable—Height in inches.
e.g. 83
injury_body_part
stringnullable—Affected body part for the most recent injury (e.g., "Knee", "Ankle"). Null when injury_status is null.
Values:anklekneeillnesshiptoebackwristfootcalfhamstringpelvisabdomenheelrestachillesthumbhand
injury_detail
stringnullable—Free-text injury description from the source feed.
e.g.
injury_since
timestamptznullable—Timestamp of the injury status snapshot. Updated when player_news produces a new injury entry.
e.g. 2026-04-12T18:30:00Z
injury_status
stringnullable—Current injury status snapshot derived from player_news. Values: "OUT", "QUESTIONABLE"; null = no active injury designation (healthy).
Values:OUTQUESTIONABLE
jersey
stringnullable—Current jersey number as a string (some leagues allow leading zeros, e.g., "00").
e.g. 15
last_affiliation
stringnullable—Most recent pre-NBA affiliation (school, league, or team).
e.g. Mega Basket / Serbia
last_name
string—Player's legal last name.
e.g. Jokić
league_slug
stringnullable—NBA-issued URL slug of the player (as in the league player page).
e.g. nikola-jokic
nba_flag
stringnullable—String "Y"/"N" indicating NBA experience. Almost always "Y" in this table.
e.g. Y
playercode
stringnullable—NBA-issued player code (lastname_firstname format).
e.g. jokic_nikola
position_category
stringnullable—Coarse positional grouping. One of Guard, Forward, Center, Utility.
Values:GuardForwardCenterUtility
primary_position
string—Primary position. One of G, F, C, G-F, F-C. (True PG/SG/SF/PF splits live in team_depth_charts.position.)
Values:GFCG-FF-CUnknown
roster_status
stringnullable—Canonical roster status, shared across leagues. NBA source granularity is coarse: "active" (on an NBA roster), "free_agent" (no team), "inactive" (not currently rostered); injured_reserve/retired appear where derivable. The "on a team now" set is {active, injured_reserve}.
Values:inactiveactivefree_agent
school
stringnullable—Last school attended before the NBA (college, prep, or international club).
e.g. Mega Basket
team_abbreviation
stringnullable—Current team's tri-letter code.
e.g. DEN
team_city
stringnullable—Current team's city name.
e.g. Denver
team_code
stringnullable—Current team's lowercase URL slug.
e.g. nuggets
team_name
stringnullable—Current team's mascot name (denormalized from teams.name for read convenience).
e.g. Nuggets
to_year
stringnullable—Player's most recent NBA season year. Equal to from_year for rookies.
e.g. 2025
weight
integernullable—Listed weight in pounds.
e.g. 284
GET/api/v1/nba/players/{id}
Parameters
idpathbigintrequired
Primary key (id) of the player row.
Restores the documented defaults (trial keys only accept the unchanged defaults).
Request
curl -sS --compressed \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  'https://api.stat-api.com/api/v1/nba/players/{pk_value}'
Responses
200Single player row.application/jsonshow example ▸
404Row not found.
Response Schema(40 fields)show schema ▸
FieldTypeReferencesDescription
idkey
bigint—Primary Key
league_player_id
integer—Official NBA player ID (issued by the league). Stable across seasons; use it to join other data that carries the league id.
e.g. 203999
team_id
bigintnullableFK to nba.teams. Null for free agents and retired players.
e.g. 12
birth_city
stringnullable—City of birth.
e.g. Sombor
birth_country
stringnullable—Country of birth (ISO English name).
e.g. Serbia
birth_date
datenullable—Birth date in YYYY-MM-DD form.
e.g. 1995-02-19
birth_state
stringnullable—State / province of birth (US/Canadian players).
e.g.
display_fi_last
stringnullable—Display name in "F. Last" form.
e.g. N. Jokić
display_last_comma_first
stringnullable—Display name in "Last, First" form. Useful for sorted lists.
e.g. Jokić, Nikola
dleague_flag
stringnullable—Two-character bit-string from the league: "00" no G-League history, "01" G-League experience, "11" currently G-League-affiliated (two-way / assignment).
e.g. 00
draft_number
stringnullable—Overall pick number within the draft (string). Empty for undrafted.
e.g. 41
draft_round
stringnullable—Draft round (string). Empty for undrafted players.
e.g. 2
draft_year
stringnullable—Year the player was drafted (string form). Empty for undrafted players.
e.g. 2014
experience
integernullable—Years of NBA experience as of the most recent season. Rookies = 0.
e.g. 10
first_name
string—Player's legal first name as registered with the league.
e.g. Nikola
from_year
stringnullable—Player's NBA debut year as a string (as the league records it).
e.g. 2015
full_name
string—Convenience concatenation of first_name + last_name. Use this for display.
e.g. Nikola Jokić
full_position_list
stringnullable—Hyphenated full-word position list (e.g., "Guard-Forward", "Center-Forward").
Values:GuardForwardCenterGuard-ForwardForward-CenterCenter-ForwardForward-Guard
games_played_flag
stringnullable—String "Y"/"N" indicating whether the player has played at least one regular-season game.
Values:YN
height
integernullable—Height in inches.
e.g. 83
injury_body_part
stringnullable—Affected body part for the most recent injury (e.g., "Knee", "Ankle"). Null when injury_status is null.
Values:anklekneeillnesshiptoebackwristfootcalfhamstringpelvisabdomenheelrestachillesthumbhand
injury_detail
stringnullable—Free-text injury description from the source feed.
e.g.
injury_since
timestamptznullable—Timestamp of the injury status snapshot. Updated when player_news produces a new injury entry.
e.g. 2026-04-12T18:30:00Z
injury_status
stringnullable—Current injury status snapshot derived from player_news. Values: "OUT", "QUESTIONABLE"; null = no active injury designation (healthy).
Values:OUTQUESTIONABLE
jersey
stringnullable—Current jersey number as a string (some leagues allow leading zeros, e.g., "00").
e.g. 15
last_affiliation
stringnullable—Most recent pre-NBA affiliation (school, league, or team).
e.g. Mega Basket / Serbia
last_name
string—Player's legal last name.
e.g. Jokić
league_slug
stringnullable—NBA-issued URL slug of the player (as in the league player page).
e.g. nikola-jokic
nba_flag
stringnullable—String "Y"/"N" indicating NBA experience. Almost always "Y" in this table.
e.g. Y
playercode
stringnullable—NBA-issued player code (lastname_firstname format).
e.g. jokic_nikola
position_category
stringnullable—Coarse positional grouping. One of Guard, Forward, Center, Utility.
Values:GuardForwardCenterUtility
primary_position
string—Primary position. One of G, F, C, G-F, F-C. (True PG/SG/SF/PF splits live in team_depth_charts.position.)
Values:GFCG-FF-CUnknown
roster_status
stringnullable—Canonical roster status, shared across leagues. NBA source granularity is coarse: "active" (on an NBA roster), "free_agent" (no team), "inactive" (not currently rostered); injured_reserve/retired appear where derivable. The "on a team now" set is {active, injured_reserve}.
Values:inactiveactivefree_agent
school
stringnullable—Last school attended before the NBA (college, prep, or international club).
e.g. Mega Basket
team_abbreviation
stringnullable—Current team's tri-letter code.
e.g. DEN
team_city
stringnullable—Current team's city name.
e.g. Denver
team_code
stringnullable—Current team's lowercase URL slug.
e.g. nuggets
team_name
stringnullable—Current team's mascot name (denormalized from teams.name for read convenience).
e.g. Nuggets
to_year
stringnullable—Player's most recent NBA season year. Equal to from_year for rookies.
e.g. 2025
weight
integernullable—Listed weight in pounds.
e.g. 284
GET/api/v1/nba/players/search
Parameters
qquerystringrequired
Search query — matches against full_name (case-insensitive).
limitqueryintegeroptionaldefault 10
Max results to return. Default 10; max 50.
Restores the documented defaults (trial keys only accept the unchanged defaults).
Request
curl -sS --compressed \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  'https://api.stat-api.com/api/v1/nba/players/search?q=example&limit=10'
Responses
200Fuzzy search NBA players by nameapplication/jsonshow example ▸
400q is empty or exceeds 100 chars
503pg_trgm extension unavailable on the DB
Response Schema(40 fields)show schema ▸
FieldTypeReferencesDescription
idkey
bigint—Primary Key
league_player_id
integer—Official NBA player ID (issued by the league). Stable across seasons; use it to join other data that carries the league id.
e.g. 203999
team_id
bigintnullableFK to nba.teams. Null for free agents and retired players.
e.g. 12
birth_city
stringnullable—City of birth.
e.g. Sombor
birth_country
stringnullable—Country of birth (ISO English name).
e.g. Serbia
birth_date
datenullable—Birth date in YYYY-MM-DD form.
e.g. 1995-02-19
birth_state
stringnullable—State / province of birth (US/Canadian players).
e.g.
display_fi_last
stringnullable—Display name in "F. Last" form.
e.g. N. Jokić
display_last_comma_first
stringnullable—Display name in "Last, First" form. Useful for sorted lists.
e.g. Jokić, Nikola
dleague_flag
stringnullable—Two-character bit-string from the league: "00" no G-League history, "01" G-League experience, "11" currently G-League-affiliated (two-way / assignment).
e.g. 00
draft_number
stringnullable—Overall pick number within the draft (string). Empty for undrafted.
e.g. 41
draft_round
stringnullable—Draft round (string). Empty for undrafted players.
e.g. 2
draft_year
stringnullable—Year the player was drafted (string form). Empty for undrafted players.
e.g. 2014
experience
integernullable—Years of NBA experience as of the most recent season. Rookies = 0.
e.g. 10
first_name
string—Player's legal first name as registered with the league.
e.g. Nikola
from_year
stringnullable—Player's NBA debut year as a string (as the league records it).
e.g. 2015
full_name
string—Convenience concatenation of first_name + last_name. Use this for display.
e.g. Nikola Jokić
full_position_list
stringnullable—Hyphenated full-word position list (e.g., "Guard-Forward", "Center-Forward").
Values:GuardForwardCenterGuard-ForwardForward-CenterCenter-ForwardForward-Guard
games_played_flag
stringnullable—String "Y"/"N" indicating whether the player has played at least one regular-season game.
Values:YN
height
integernullable—Height in inches.
e.g. 83
injury_body_part
stringnullable—Affected body part for the most recent injury (e.g., "Knee", "Ankle"). Null when injury_status is null.
Values:anklekneeillnesshiptoebackwristfootcalfhamstringpelvisabdomenheelrestachillesthumbhand
injury_detail
stringnullable—Free-text injury description from the source feed.
e.g.
injury_since
timestamptznullable—Timestamp of the injury status snapshot. Updated when player_news produces a new injury entry.
e.g. 2026-04-12T18:30:00Z
injury_status
stringnullable—Current injury status snapshot derived from player_news. Values: "OUT", "QUESTIONABLE"; null = no active injury designation (healthy).
Values:OUTQUESTIONABLE
jersey
stringnullable—Current jersey number as a string (some leagues allow leading zeros, e.g., "00").
e.g. 15
last_affiliation
stringnullable—Most recent pre-NBA affiliation (school, league, or team).
e.g. Mega Basket / Serbia
last_name
string—Player's legal last name.
e.g. Jokić
league_slug
stringnullable—NBA-issued URL slug of the player (as in the league player page).
e.g. nikola-jokic
nba_flag
stringnullable—String "Y"/"N" indicating NBA experience. Almost always "Y" in this table.
e.g. Y
playercode
stringnullable—NBA-issued player code (lastname_firstname format).
e.g. jokic_nikola
position_category
stringnullable—Coarse positional grouping. One of Guard, Forward, Center, Utility.
Values:GuardForwardCenterUtility
primary_position
string—Primary position. One of G, F, C, G-F, F-C. (True PG/SG/SF/PF splits live in team_depth_charts.position.)
Values:GFCG-FF-CUnknown
roster_status
stringnullable—Canonical roster status, shared across leagues. NBA source granularity is coarse: "active" (on an NBA roster), "free_agent" (no team), "inactive" (not currently rostered); injured_reserve/retired appear where derivable. The "on a team now" set is {active, injured_reserve}.
Values:inactiveactivefree_agent
school
stringnullable—Last school attended before the NBA (college, prep, or international club).
e.g. Mega Basket
team_abbreviation
stringnullable—Current team's tri-letter code.
e.g. DEN
team_city
stringnullable—Current team's city name.
e.g. Denver
team_code
stringnullable—Current team's lowercase URL slug.
e.g. nuggets
team_name
stringnullable—Current team's mascot name (denormalized from teams.name for read convenience).
e.g. Nuggets
to_year
stringnullable—Player's most recent NBA season year. Equal to from_year for rookies.
e.g. 2025
weight
integernullable—Listed weight in pounds.
e.g. 284