New Endpoints + General Endpoint Groupings

[ghost]

Hi all,

First off I really appreciate your work on this repo, it has been such a fun thing to use for my personal project. I saw some new endpoints added as I was looking for a schedule based endpoint. It got me thinking, there's a general structure, and you've documented usage of these endpoints quite well as well as package structure mapped out. But, is there any "general usage" documentation regarding which endpoints are typically used together, etc? I would love to help out with this when I get the opportunity, as I've been looking for something like this myself. I've found that certain player dashboards have the same endpoints, and same outputs, and therefore fit well in a front end together - etc.

I imagine this has implications for number of API calls as well, understanding how this overlap exists!

Thank you so much.

-slyle

[slyyyle]

I also would love instruction on keeping endpoint analysis up to date, or perhaps I missed the docs. I am essentially trying to circumvent having to grab get_dict() for some of the complex boxscores, which means I have to pull the metadata or "schema" from the endpoint analysis file, which for now I've saved a hardcoded copy of one from 5 months ago, but it seems to be missing BoxScore endpoints.

-I do this for ease of use with more nested objects. -I lump certain dataframes together using a react data grid that can dynamically init based on information from the data object. However, I couldn't find the name of each dataframe as the return of get_data_frames() is a list of dataframes, naturally. This "grouping" of data frames for a personal front end app makes navigation and EDA much easier - this becomes problematic for "like" endpoints that have different params or expected JSON response structures.

Thanks!

[rsforbes]

@slyyyle - Please post your code.

[slyyyle]

In what regard? All my questions above were regarding how the package works.

I have found get_json() solves most issues with the API pull - the result set names are nicely there for use.

However, it leads me back to my first question:

Is there, or is it worth making, documentation that is holistic regarding not technical use of the package, but "overall use".

For example get_json() is great for web dev, and has certain info get_data_frames() doesn't have - like name of result set. This is all 100% implicit and fine the way it is - it's not like it's hidden.

Other examples are the player dashboards lump great together because their parameters are the same. Sometimes setting 0 to a parameter is a good thing to try. The difference between player_dash and player_dashboard in use. I tooled it out, but it was kinda difficult. Maybe it was just me?

[slyyyle]

Something like the below perhaps? It'd be redundant, but a softer intro to the package. (#3 primarily)

Tips & Tricks for nba_api

The nba_api package offers several ways to retrieve and work with data from NBA.com endpoints. Here are some key tips and tricks that can help you streamline your workflow:

1. Understanding the Package and Documentation

• Documentation Location:

  • VERY useful documentation is housed in the Docs folder. This includes detailed examples, endpoint schema, and what each endpoints' outputs look like.

• Live Endpoints:

  • Boxscore: Provides game summary details for live or recently completed games.
  • Scoreboard: Ideal for retrieving current game scores and schedules. (Use scoreboardv2 in stats endpoints for future and previous day scoreboards! DayOffset is great!)
  • PlayByPlay: Perfect for tracking the in-game action in real time.

• Stats Endpoints:

  • Best for accessing historical data, projections, and other detailed statistics.

• Static Data:

  • Great for tasks like exchanging IDs for names, searching for players by name, or finding teams by name—without the need to make an actual API call.
  • Use these endpoints to quickly access reference data and reduce the number of API requests.

2. Choosing the Right Data Return Method

• get_json()
  Ideal for web development when you need:
  • A JSON string with useful metadata.
  • Easily typeable data objects for further processing.
• get_data_frames()
  Perfect for working in interactive environments like Jupyter notebooks or UI libraries such as Streamlit:
  • Returns a list of pandas DataFrames.
  • Facilitates quick data manipulation and visualization.
• get_dict()
  Handy in cases where the structure is a bit more complex or less defined:
  • Returns the API data as a dictionary.
  • Useful when you need to inspect nested structures or when the data format is less straightforward.

3. Understanding Endpoint Categories

• Player Dashboard Endpoints
  • These endpoints are designed for a “general dashboard” vibe.
  • They tend to share the same parameters, which makes them easy to generalize on the back end.
• Player Dash Endpoints
  • These are tailored for more specific stat tracking.
  • Their parameters are often more targeted toward the stat type you want to track.

Use the endpoint that best fits your use case:

• General Overview: Use player_dashboard endpoints.
• Detailed Analysis: Use player_dash endpoints for more granular data.

(THIS COULD BE EXPANDED, I don't have other examples for now)

4. Handling Variations in API Responses

Depending on how you access the data and which endpoint you’re calling, you might encounter differences in the API return:

• Key Differences:
  Some endpoints may return data under the keys resultSets or data_sets.
  • Always check the response structure.
  • Write a small wrapper or helper function to standardize the data extraction.