The HoopTotals API enables website owners and developers to integrate the HoopTotals data service into their web applications. Using our API specification, applications can query the HoopTotals database and obtain specific data on players, teams, and lines.
How It Works
The Basics
A GET request is made to the HoopTotals API script, with various parameters passed that specify the data to be extracted from the database. The requested URL takes the following form:http://www.hooptotals.com/api.php?parameter1=value1¶meter2=value2&...
The HoopTotals API script then returns a record set in XML or JSON format, or an error message if the request was improperly formatted.
Example
The following request will return the number of points, assists, and offensive rebounds made by Tim Duncan in the 2002-2003 season during the first few days of March:http://www.hooptotals.com/api.php?
key=XXXX
&object=player
&season=2002
&name=Tim Duncan
&fields=pts,ast,orb
&mindate=2003-03-01
&maxdate=2003-03-05
&format=xml
The output from this request will be the following XML document:
<?xml version="1.0" encoding="utf-8"?>
<response>
<rowset>
<row>
<date>2003-03-04</date>
<pts>35</pts>
<ast>8</ast>
<orb>8</orb>
</row>
<row>
<date>2003-03-02</date>
<pts>17</pts>
<ast>3</ast>
<orb>0</orb>
</row>
<row>
<date>2003-03-01</date>
<pts>18</pts>
<ast>2</ast>
<orb>4</orb>
</row>
</rowset>
</response>
If the format parameter were set to json, the output would be the following:
{
"response":{
"rowset":[
{
"date":"2003-03-04",
"pts":"35",
"ast":"8",
"orb":"8"
},
{
"date":"2003-03-02",
"pts":"17",
"ast":"3",
"orb":"0"
},
{
"date":"2003-03-01",
"pts":"18",
"ast":"2",
"orb":"4"
}
]
}
}
If the request results in an error, most likely due to a syntax error in the URL, the HoopTotals API script will produce a response of the form:
<?xml version="1.0" encoding="utf-8"?>
<response>
<error>Error Message</error>
</response>
or the following, if format=json:
{
"response":{
"error":"Error Message"
}
}
Parameters
The following parameters are passed to the HoopTotals API script in the requesting URL:| key | (required) The developer's API key, obtained upon subscription to the HoopTotals API. |
| object | (required) The type of object for which data is being requested. Must be one of player, team, or line. |
| season | (required) The season for which data is being requested, equal to the year of the season's scheduled start. The HoopTotals database contains team and player data from the current season going back to 1993, and betting line data from the current season going back to 1999. |
| name | (required for object=player or object=team) The name of the player or team for which data is being requested, e.g. Lebron James or Phoenix Suns. |
| fields | (required) A comma-delimited list of the requested data fields, e.g. blk,stl,drb. The set of available fields depends on the value of object, detailed below. |
| mindate | (optional) The minimum date for which to return data. Must be in the format YYYY-MM-DD. |
| maxdate | (optional) The maximum date for which to return data. Must be in the format YYYY-MM-DD. |
| format | (optional) The format in which to output the response (either XML or JSON). The default format is XML. |
| callback | (optional) If format=JSON, the response can wrap the resulting JSON object in a specified callback function. This technique is known as "JSON with padding" and enables cross-domain data requests directly from JavaScript. |
Data Fields
The set of data fields that can be requested depends on the value of the object parameter.For object=player, the following fields are available:
| away | The away team of the given game. |
| home | The home team of the given game. |
| team | The team the specified player was playing for. |
| starter | Equal to 1 or 0, depending on whether the player was a starter or a reserve. |
| min | Minutes played. |
| fg | Field goals. |
| fga | Field goal attempts. |
| tp | Three-point field goals. |
| tpa | Three-point field goal attempts. |
| ft | Free throws. |
| fta | Free throw attempts. |
| orb | Offensive rebounds. |
| drb | Defensive rebounds. |
| ast | Assists. |
| stl | Steals. |
| blk | Blocks. |
| tno | Turnovers. |
| pf | Personal fouls. |
| pts | Points. |
| away | The away team of the given game. |
| home | The home team of the given game. |
| min | Minutes played. |
| fg | Field goals. |
| fga | Field goal attempts. |
| tp | Three-point field goals. |
| tpa | Three-point field goal attempts. |
| ft | Free throws. |
| fta | Free throw attempts. |
| orb | Offensive rebounds. |
| drb | Defensive rebounds. |
| ast | Assists. |
| stl | Steals. |
| blk | Blocks. |
| tno | Turnovers. |
| pf | Personal fouls. |
| pts | Points. |
| ofg | Opponent field goals. |
| ofga | Opponent field goal attempts. |
| otp | Opponent three-point field goals. |
| otpa | Opponent three-point field goal attempts. |
| oft | Opponent free throws. |
| ofta | Opponent free throw attempts. |
| oorb | Opponent offensive rebounds. |
| odrb | Opponent defensive rebounds. |
| oast | Opponent assists. |
| ostl | Opponent steals. |
| oblk | Opponent blocks. |
| otno | Opponent turnovers. |
| opf | Opponent personal fouls. |
| opts | Opponent points. |
| away | The away team of the given game. |
| home | The home team of the given game. |
| awayspread | The spread for the away team. |
| homespread | The spread for the home team. |
| total | The total. |