Skip to main content

​
Overview

This endpoint retrieves the complete list of NBA players for the current season. It uses the nba_api.PlayerIndex to fetch player data and includes a fallback mechanism to ensure data availability.

​
Authentication

This endpoint requires authentication. The user must have a valid session token.

​
Response

Returns an array of player objects with the following structure:
​
id
integer
required
The unique NBA player ID (PERSON_ID)
​
full_name
string
required
Player’s full name (first name + last name)
​
team_id
integer
The player’s current team ID. May be null if not assigned to a team.
​
team_abbreviation
string
required
The team’s abbreviation (e.g., “LAL”, “BOS”). Shows “N/A” in fallback mode.
​
position
string
required
Player’s position (e.g., “G”, “F”, “C”). Shows “N/A” in fallback mode.

​
Implementation Details

​
Primary Method

The endpoint uses nba_api.playerindex.PlayerIndex with the following parameters:
  • season: Current NBA season (e.g., “2023-24”)
  • league_id: “00” (NBA league)
from nba_api.stats.endpoints import playerindex

season_str = current_nba_season()
player_data_df = playerindex.PlayerIndex(
    season=season_str, 
    league_id="00"
).get_data_frames()[0]

​
Fallback Method

If the primary method fails, the endpoint falls back to nba_api.stats.static.players.get_active_players(): 
from nba_api.stats.static import players as nba_static_players

active_players_basic = nba_static_players.get_active_players()
players_list_fallback = [
    {
        'id': p['id'], 
        'full_name': p['full_name'], 
        'team_id': None,
        'team_abbreviation': 'N/A', 
        'position': 'N/A'
    } 
    for p in active_players_basic
]

​
Example Response

[
  {
    "id": 2544,
    "full_name": "LeBron James",
    "team_id": 1610612747,
    "team_abbreviation": "LAL",
    "position": "F"
  },
  {
    "id": 201939,
    "full_name": "Stephen Curry",
    "team_id": 1610612744,
    "team_abbreviation": "GSW",
    "position": "G"
  },
  {
    "id": 203999,
    "full_name": "Nikola Jokic",
    "team_id": 1610612743,
    "team_abbreviation": "DEN",
    "position": "C"
  }
]

​
Error Handling

The endpoint implements a two-tier error handling strategy:
  1. Primary Failure: If PlayerIndex fails, the system logs the error and attempts the fallback method
  2. Fallback Failure: If both methods fail, returns a 500 error with the message “Failed to fetch NBA players list”
  3. Authentication Failure: Returns a 401 error if the user is not authenticated

​
Usage Notes

  • The endpoint automatically detects the current NBA season
  • Player data is fetched in real-time from the NBA API
  • The fallback method provides basic player information but excludes team and position details
  • Response includes all active NBA players for the current season

Build docs developers (and LLMs) love

Get started for freeTalk to us