Marketplace engineering-nba-data

Goal: Extract and process NBA statistical data efficiently using the nba_api library for data analysis, reporting, and application development.

IMPORTANT: The nba_api library accesses stats.nba.com endpoints. All data requests return structured datasets that can be output as JSON, dictionaries, or pandas DataFrames.

Workflow

Phase 1: Setup and Installation

• Install nba_api:

  pip install nba_api

  if not yet installed
• Import required modules based on task:

  • from nba_api.stats.endpoints import [endpoint_name]

    for stats.nba.com data

  • from nba_api.stats.static import players, teams

    for static lookups

  • from nba_api.stats.library.parameters import [parameter_classes]

    for valid parameter values

Phase 2: Data Retrieval

For Player/Team Lookups (No API Calls):

• Use

  players.find_players_by_full_name('player_name')

  for player searches
• Use

  teams.find_teams_by_full_name('team_name')

  for team searches
• Both return dictionaries with

  id

  ,

  full_name

  , and other metadata
• No HTTP requests are sent; data is embedded in the package

For Stats Endpoints (API Calls):

• Identify the correct endpoint from table of contents
• Initialize endpoint with required parameters:

  endpoint_class(param1=value1, param2=value2)

• Access datasets using dot notation:

  response_object.dataset_name

• Retrieve data in desired format:

  • .get_json()

    for JSON string

  • .get_dict()

    for dictionary

  • .get_data_frame()

    for pandas DataFrame

Custom Request Configuration:

• Set custom headers:

  endpoint_class(player_id=123, headers=custom_headers)

• Set proxy:

  endpoint_class(player_id=123, proxy='127.0.0.1:80')

• Set timeout:

  endpoint_class(player_id=123, timeout=100)

  (in seconds)

Phase 3: Data Processing

• Extract specific datasets from endpoint responses
• Transform data using pandas for aggregations, filtering, joins
• Normalize nested data structures as needed
• Handle multiple datasets returned by single endpoint

Phase 4: Output and Storage

• Export to CSV:

  df.to_csv('output.csv', index=False)

• Export to JSON: Use

  .get_json()

  or

  df.to_json()

• Store in database using pandas

  .to_sql()

  method
• Cache responses to minimize API calls

Rules

• Required packages:

  nba_api

  must be installed before use
• Static first: Always use static lookups (players/teams) for ID retrieval before making API calls
• Parameter validation: Reference parameters.md for valid parameter values
• Endpoint selection: Check table of contents to find the correct endpoint
• Rate limiting: Be mindful of API rate limits; cache data when possible
• Error handling: Wrap API calls in try-except blocks to handle network failures
• Data formats: Know when to use JSON, dict, or DataFrame based on downstream requirements
• Season format: Seasons use format

  YYYY-YY

  (e.g.,

  2019-20

  )
• League IDs: NBA=

  00

  , ABA=

  01

  , WNBA=

  10

  , G-League=

  20

Acceptance Criteria

• Data retrieved successfully from appropriate endpoint or static source
• Correct parameters used based on documentation
• Data formatted appropriately for intended use case
• Error handling implemented for API failures
• Code follows Python best practices
• Results validated against expected structure
• Documentation references included where relevant

Reference Documentation

Quick access to common resources:

• Table of Contents - Full documentation index
• Examples - Usage examples for endpoints and static data
• Parameters - Valid parameter values and patterns
• Endpoints Data Structure - Response format and methods
• Players - Static player lookup functions
• Teams - Static team lookup functions
• HTTP Library - HTTP request details

Endpoint-specific documentation:

Refer to

docs/nba_api/stats/endpoints/[endpoint_name].md

for detailed parameter and dataset information for each endpoint.