Requests

Any time you wish to poll NBA data, you must send a request to the client. There is an individual request class for all 253 requests. Simply browse the GitHub code or this site's request reference to find the request that you want, create an instance of that request with all required parameters and filters, and send it across to the client. For example:

use JasonRoman\NbaApi\Client\Client;
use JasonRoman\NbaApi\Request\Data\Prod\General\TodayRequest;

$client  = new Client();
$request = TodayRequest::fromArray(); // fromArray() is recommended

$response = $client->request($request);

Request Types / Organization

In order to give some organization across the 253 requests, all requests are organized into a hierarchy of 3 identifiers: Domain, Section, and Category. So the Request class with namespace

JasonRoman\NbaApi\Request\Data\Prod\Game\BoxscoreRequest

has the following properties:

Domain: Data
Section: Prod
Category: Game

For reference, the endpoint for this request is

http://data.nba.net/prod/v1/{gameDate}/{gameId}_boxscore.json

Notice that Domain ties in to http://data.nba.net and Section ties in to /prod, and that is the basis for all requests. Category refers to the type of data that is being returned.

Parameters

Most requests require that you pass in parameters to retrieve data. For example, retrieving a specific box score might require entering the game date and game id. You can easily do this by passing in an array to your request, like so:

use JasonRoman\NbaApi\Request\Data\Prod\Game\BoxscoreRequest;

$request = BoxScoreRequest::fromArray([
    'gameDate' => new \DateTime('2017-02-01'),
    'gameId'   => '0021600732',
]);

All parameters are translated into the URL itself and/or passed along in the query string, so the client has to turn them into strings. However, when creating requests through the NBA API, you set parameters as the corresponding PHP data type that matches the parameter.

You can view the Parameters tab on an individual request to see which parameters are required, their data type, and allowed values.

Since you will likely know all of the parameters you want to set in your request, it is recommended to use this fromArray() function to create a new instance of your request. If you wish to instantiate a new request object and set the parameters manually, you can do that as well:

use JasonRoman\NbaApi\Request\Data\Prod\Game\BoxscoreRequest;

$request = new BoxScoreRequest(); // alternative instantiation

$request->gameDate = new \DateTime('2017-02-01');
$request->gameId   = '0021600732';

Default Parameter Values

Many parameters have default values. For instance, requests that have a League ID parameter will usually default to 00, which is the league ID for the NBA (the G-League is 20). When a parameter has a default value, you do not have to explicitly pass it in when creating your request. For example, the following lines of code are equivalent in creating a request that will get the franchise history for all NBA teams:

use JasonRoman\NbaApi\Request\Stats\Stats\Teams\FranchiseHistoryRequest;

$request = FranchiseHistoryRequest::fromArray();
$request = FranchiseHistoryRequest::fromArray(['leagueId' => '00']);

Of course, you can override any defaults when creating the request. Let's modify the previous request to get the franchise history for all G-League teams:

use JasonRoman\NbaApi\Params\LeagueIdParam;
use JasonRoman\NbaApi\Request\Stats\Stats\Teams\FranchiseHistoryRequest;

$request = FranchiseHistoryRequest::fromArray(['leagueId' => LeagueIdParam::G_LEAGUE]);

Notice that instead of hard-coding the value of 20 directly, we used a constant from the LeagueIdParam class. This library comes with 100s of useful parameter constants that can be leveraged instead of hard-coding values, and helps avoid typos and mistakes when setting values.

Example Parameter Values

I wanted to make this library as simple as possible, so I created example values for every single request. These automatically fill in all required parameters that do not have default values. With this, you can create a valid request object for any of the 253 requests with just a single line of code. For example:

use JasonRoman\NbaApi\Request\Data\Prod\Game\BoxscoreRequest;

$request = BoxscoreRequest::fromArrayWithExamples();

The GameDateParam has a default value of new \DateTime('2017-02-01'), and GameIdParam has a default value of '0021600732'. Normally, you have to fill in these 2 parameters yourself in the fromArray() function, but using the above fromArrayWithExamples() function you can have a ready-made request in a single line.

Again, this library is flexible. You may override any of these example values while using this function to create your request.