NBA_app

Flask-based NBA statistics API and demo client built on top of nba_api.

The project exposes endpoints for:

• player stats and rankings,
• team stats and rankings,
• draft-player queries,
• award-based leaderboards.

It also includes a Python client (client/client_main.py) and a pytest suite (test/).

Project Structure

client/      Flask launcher + demo client
data/        Domain models and business logic (calls nba_api)
endpoints/   Flask blueprints and Swagger UI integration
library/     Local JSON persistence for add/delete overrides
test/        Unit and integration-style tests

Requirements

• Python 3.9 is declared in Pipfile.
• Dependencies are pinned in requirements.txt.
• Internet access is required for most features/tests because data is fetched from nba_api.

Setup

Option 1: venv + pip

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Option 2: pipenv

pipenv install
pipenv shell

Run The API

From the repository root:

python -m client.app

Default URL: http://127.0.0.1:5000

Swagger UI: http://127.0.0.1:5000/api/docs

Run Demo Client

With the API running in another terminal:

python -m client.demo

Run Tests

pytest test/

Note: tests call live NBA endpoints (nba_api), so network latency or upstream changes can affect results.

API Reference

Base URL: http://127.0.0.1:5000

Players

• GET /players/by

  • Required query params: method, value
  • Supported filter param sets:
    • season
    • season + mode (Totals or PerGame)
    • season + mode + season_type

• GET /players/ranking

  • Required query params: top_n, stat
  • Supported filter param sets: season; season + mode; season + mode + season_type

• GET /players/compare

  • Required query params: player_1, player_2
  • Supported filter param sets: season; season + mode; season + mode + season_type

• GET /players/top10

  • Required query param: type (offensive or defensive)
  • Supported filter param sets: season; season + mode; season + mode + season_type

• GET /players/mvp_predictor

• POST /players/add

  • JSON body must match the underscore-prefixed fields used by the code, for example:

{
	"_id": 333333,
	"_rank": 333,
	"_first_name": "Amos",
	"_last_name": "Colombo",
	"_team": "MIL",
	"_gp": 30,
	"_fgm": 100,
	"_fga": 3,
	"_fg3m": 3,
	"_fg3a": 3,
	"_ftm": 3,
	"_fta": 3,
	"_o_reb": 3,
	"_d_reb": 3,
	"_ast": 3,
	"_steal": 3,
	"_block": 3,
	"_turnovers": 3,
	"_fouls": 3,
	"_points": 200,
	"_efficiency": 30
}

• DELETE /players/delete
  • JSON body: { "id": <player_id> }

Teams

• GET /teams/by

  • Required query params: method, value
  • Optional query param: season

• GET /teams/ranking

  • Required query params: top_n, stat
  • Optional query param: season

• GET /teams/best

  • Required query param: season

• POST /teams/add

  • Example JSON body:

{
	"_id": 33333,
	"_city": "Columbus",
	"_name": "Reapers",
	"_conference": "west",
	"_conference_record": [10, 0],
	"_division": "south-west",
	"_wins": 10,
	"_losses": 0,
	"_home": 5,
	"_road": 5,
	"_last_10": [10, 0],
	"_win_streak": 10,
	"_loss_streak": 0,
	"_current_streak": 10
}

• DELETE /teams/delete
  • JSON body: { "id": <team_id> }

Draft Players

• GET /draft-players/by

  • Required query params: method, value
  • Optional query param: season_year

• GET /draft-players/first_p_vs_best_r

  • Required query params: season, stat, mode

• POST /draft-players/add

  • Example JSON body:

{
	"_p_id": 333,
	"_first_name": "Amos",
	"_last_name": "Junior",
	"_season_year": 2021,
	"_round_n": 3,
	"_round_p": 333,
	"_overall_p": 333,
	"_draft_type": "-",
	"_t_id": 33333,
	"_t_city": "Milwaukee",
	"_t_name": "Bucks",
	"_t_abb": "MIL",
	"_org": "Supsi",
	"_org_type": "college"
}

• DELETE /draft-players/delete
  • JSON body: { "id": <player_id>, "season": <season_year> }

Awards

• GET /awards/ranking
  • Required query params: top_n, award_name

Useful cURL Examples

curl "http://127.0.0.1:5000/players/by?method=name&value=Stephen%20Curry&season=2020-21"
curl "http://127.0.0.1:5000/players/ranking?season=2020-21&top_n=10&stat=points"
curl "http://127.0.0.1:5000/teams/best?season=2020-21"
curl "http://127.0.0.1:5000/draft-players/first_p_vs_best_r?season=2020-21&stat=points&mode=Totals"
curl "http://127.0.0.1:5000/awards/ranking?top_n=10&award_name=NBA%20All-Star%20Most%20Valuable%20Player"

Notes And Caveats

• Swagger (/api/docs) is useful, but some parameter names there do not perfectly match implementation.
  • Example: implementation expects method (not methods) in /players/by, /teams/by, /draft-players/by.
• For player routes, mode/season_type are not fully independent in the current implementation.
  • Reliable combinations are: season; season + mode; season + mode + season_type.
• Delete endpoints are implemented with JSON request bodies (request.get_json()), even if Swagger shows query params.
• Add/delete operations persist changes in:
  • library/players_add.json, library/players_delete.json
  • library/teams_add.json, library/teams_delete.json
  • library/draft_add.json, library/draft_delete.json