Introduction

Most of the methods use a RESTful API design. This means that you make use of the standard HTTP methods (GET, POST, DELETE, PUT).

This API is designed to be used by external parties (as well as internal) to get information about one or many games. It is designed to return information relevant to the games at a specific time, it is not deisgned to be used to gather historical information about past games.

The API will be hosted in two separate locations:

Arena. The in arena endpoint will only support making calls about the match that is currently in progress at that specific arena.
Centrally The central endpoint will support making calls about any match.

In Arena users can call the central endpoint to gather information about other matches.

Common Parameters

While different methods require different data either as part of the URL, the query string or request body there are some parameters that are common to all API methods. These are passed as optional query parameters.

limit integer	Limit the number of records returned by the method. Default is 10, the maximum is 500. See Paging for more information.
offset integer	Ignore the first number of records in the result. See Paging for more information.
responseOk enum	The request should always return a HTTP status code of 200, regardless of any errors. `0` Return appropriate response code (Default) `1` Always return 200
format enum	The format to return the data in. `json` JSON (Default) `xml` XML

Authentication

Each API call must include the API key. It is this API key that identifies each call and applies any permissions or quotas. You will be provided this key on signup and you should keep it secret.

The API Key must be included as a HTTP header in each request. The header name is x-api-key.

Character Set

All data provided to these API functions is required to be in UTF-8 format.

All responses will be provided as UTF-8 strings.

Response Format

All responses to API calls will return in the following format

`response`
	`meta`
		`version`	The version of the API in use
		`code`	The HTTP status code of the response. Options are: `200` Ok `400` Bad Request. The information you passed into the call was missing or incorrect. `401` Unauthorised. The API key used does not have permission to perform the action you have requested. `404` Not Found. The function cannot be found. `500` Internal Server Error. There was an error on the server.
		`status`	The status of the response. Options are: `success` `failure` If the bulk parameter is used in the call then the status of the call will be a success even if all the individual data elements generate errors.
		`request`	The request path/query string for which this is the response
		`time`	ISO-8601 formatted timestamp indicating when the response was generated.
		`count`	For a successful request, how many records are being returned
		`limit`	For this request, what was the record limit being applied
	`data`
		Successful Requests
			For successful requests this node will contain the information that is specified to be returned in the documentation for the individual call.
		Unsuccessful Requests
		`error`	The type of error. Options: `KEY_INVALID` The API key is not valid `NOTFOUND` You have requested an invalid action `NOTAUTHORISED` You do not have permission to perform that action on the data you have requested `DATA_INVALID` Some or all of the data you provided with the API call is missing/invalid `ERROR` An error that doesn't fit into the above categories, you should check the description for more information.
		`description`	A more detailed description of the error, if available.

From time to time new key values/structures will be added to these calls. Any client consuming this data should ignore anything they do not understand. New fields/values/structures should not cause a failure or crash in the client system.

Paging

Each API call returns 10 records to a maximum of 500 records, based on the use of the limit parameter. However if there are more than 500 records available these records can be accessed by using the offset parameter.

The offset parameter will return 'limit' rows of data starting at the 'offset + 1' row.

As part of the response meta data there are two fields, limit and count. If limit == count then you should make another call with offset = limit+1.

Example

Returns records 1 - 10

/leagues/nba/games?ak=YOUR-API-KEY&limit=10

Returns records 11 - 20

/leagues/nba/games?ak=YOUR-API-KEY&limit=10&offset=10

Games

A game is the actual sporting event between two teams that occurs at a particular date and time.

get

Get a list of games available

get

Get a game by gameId

Game Data

Detailed information from the game

get

get

get

get

get

get

get

get

Play by Play Action Types

For a particular action an event can have 1 type, 1 subtype, 1 descriptor and any number of qualifiers

If qualifiers are able to be used for a particular action/subType, then any number of qualifiers may be applied to the action.

If the subType indicates (blank) this means that the action can be used without a subType.

Type	SubType	Descriptor	Qualifiers
`game`
	`start`
	`end`
`period`
	`start`
	`end`
`2pt`			Applies to all 2pt subTypes: `2ndchance` `fastbreak` `fromturnover` `defensivegoaltending` `pointsinthepaint` `heave`
	(blank)
	`dunk`	(blank) `reverse` `alleyoop` `putback` `tip` `driving` `drivingreverse` `running` `runningreverse` `runningalleyoop` `cutting`
	`layup`	(blank) `reverse` `alleyoop` `fingerroll` `putback` `tip` `driving` `drivingreverse` `drivingfingerroll` `running` `runningreverse` `runningfingerroll` `runningalleyoop` `cutting` `cuttingfingerroll`
	`hook`	(blank) `bank` `driving` `drivingbank` `turnaround` `turnaroundbank`
	`jumpshot`	(blank) `bank` `floating` `drivingbank` `drivingfloating` `drivingfloatingbank` `turnaround` `turnaroundbank` `turnaroundfadeaway` `turnaroundfadeawaybank` `fadeaway` `fadeawaybank` `stepback` `stepbackbank` `pullup` `pullupbank` `running` `runningpullup`
`3pt`			Applies to all 3pt subTypes: `2ndchance` `fastbreak` `defensivegoaltending` `fromturnover` `heave`
	(blank)
	`jumpshot`	(blank) `bank` `floating` `drivingbank` `drivingfloating` `drivingfloatingbank` `turnaround` `turnaroundbank` `turnaroundfadeaway` `turnaroundfadeawaybank` `fadeaway` `fadeawaybank` `stepback` `stepbackbank` `pullup` `pullupbank` `running` `runningpullup`
`freethrow`		Applies to all freethrow subTypes: (blank) `flagrant`	Applies to all freethrow subTypes: `fastbreak` `fromturnover`
	`1of1`	`technical`
	`1of2`	`clearpath`
	`1of3`
	`2of2`	`clearpath`
	`2of3`
	`3of3`
	`1for1`
	`1for2`
	`1for3`
`jumpball`
		(blank)
		`startperiod`
		`lodgedball`
		`heldball`
		`doubleviolation`
		`outofbounds`
		`challenge`
	`tap`
		`unclearpass`
		`doublefoul`
	`won`
	`lost`
	`recovered`	`team`
`assist`
`block`
	`received`
`rebound`			Applies to all subTypes: `team` `deadball`
	`defensive`
	`offensive`
`foul`			Applies to all foul subTypes: `1freethrow` `2freethrow` `3freethrow` `inpenalty`
	`offensive`	Applies to offensive subType: `charge` `offtheball`
	`personal`	Applies to all personal foul subType: `take` `double` `shooting` `clearpath` `looseball` `blocking` `playercontrol` `shootingblock` `elbow` `punching` `flagranttype1` `flagranttype2` `awayfromplay` `inbound`
	`technical`	Applies to technical subType: (blank) `non-unsportsmanlike` `rimhanging` `double` `delay` `taunting` `indirect` `excesstimeout` `toomanyplayers` `defensive3second` `flopping` `bench`	`team`
	`drawn`
`timeout`			`mandatory`
	`full`	Mandatory qualifier only applies for full timeout
	`short`
	`officials`
	`challenge`
	`reset`
`steal`
`turnover`
	(blank)		`team`
	`toomanyplayers`		`team`
	`excesstimeout`		`team`
	`offensivefoul`
	`basketfrombelow`
	`swingingelbows`
	`punchedball`
	`oppositebasket`
	`palming`
	`jumpballviolation`
	`laneviolation`
	`inbound`
	`discontinuedribble`
	`lostball`
	`offensivegoaltending`
	`badpass`
	`backcourt`
	`doubledribble`
	`outofbounds`	`lostball` `badpass` `step`
	`traveling`
	`shotclock`		`team`
	`3secviolation`
	`5secviolation`
	`8secviolation`
	`5secinboundviolation`		`team`
	`offensivekickedball`
	`illegalassist`
	`illegaloutofboundscreen`
	`5secondbacktothebasket`
	`10secondfreethrowshooter`
`substitution`			`startperiod`
	`in`
	`out`
`violation`
	(blank)
	`delayofgame`
	`defensivegoaltending`
	`defensive3second`
	`lane`
	`jumpball`
	`kickedball`
	`doublelane`
`ejection`
	(blank)
	`technical`
	`secondtechnical`
	`secondflagranttype1`
	`flagranttype2`
	`other`
`stoppage`
	(blank)
	`outofbounds`
	`equipmentmalfunction`
	`bloodrule`
	`courtcleanup`
	`injury`
	`other`
`instantreplay`
	`challenge` `request` `replaycenter`	`support` `overturned` `stands` applies only for request and challenge. Not for altercationrequest.

	`altercationrequest`
`memo`			The memo text should be in the value field

Court Definitions

Coordinates

Court coordinates are dimensionless and are defined as percentage measurments of the total width and height of the basketball court. The origin (0,0) is the top left corner of the court meaning the bottom right point is (100,100).

Actual physical dimensions can be obtained by multiplying the x and y values by the width and height of the court respectively.

For example: x = 20,45 relates to (20*94/100), (45*50/100) = 18.8ft, 22.5 ft

The bottom of the court (x=0) is defined as the side where the score bench is located.

Court area

Each action comes through with two shot areas, area and areaDetail. These are defined by ruleset, but they break the court up into a number of different zones. Each shot taken is assigned to one simple zone and one detail zone depending on where the person was when the action was taken.

Each one of these zones is given a name which is returned in the data.

As the zones and their names change depending on configuration, they are not defined here, but can be obtained by contacting the NBA.

Example:

An example zone layout is shown, which each colour representing a different zone, which would return a different name.