The Team Website API allows you to get access to the same data available through a standard iScore
Team Website purchase in a programmatic way.
You control access by setting an API password that will allow you or a developer of your choice to
access the data. Set the API password for your Team Website by logging into your Team Website with
your Admin password, and going to the Settings screen. There is a place to enter your API password
there.
Overview
Team Websites are an easy and powerful way to share your scoring information with others. You can
have a complete team website with a simple purchase that is updated automatically any time you
export your data from iScore. This site can be customized in many way as seen in this
Sample Gallery of team websites.
Sometimes users will already have an existing Team Website that they would prefer to add data
to, or sometimes teams will have a developer creating a complete site for them. You can
use any of the pages from your Team Website as an IFRAME reference from any other site to embed
the pre-formatted content into your own website. This allows complete integration of iScore
data into any existing websites
There may still be times when this is not quite enough, and a team decides they would like to use
the raw data from their site to do something beyond what the website can handle. That may be
adding some additional functionality that the iScore Team Websites do not already handle, or it
may just be some custom formatting or deeper integration that is not available with IFRAMEs. In
these cases, the Team Website API may be just what you are looking for.
With the Team Website API, developers can get access to all the data available through iScore
Team Websites in a programmatic way. You can get access to all the same data that goes into
making up the iScore Team Websites as raw XML or JSON, and use it to use any way you like. This
document describes that API in more detail.
Usage
Using the Team Website API is very straightforward. You send HTTP requests to the server, and
get back a response with the data you request. Every request requires that you pass an API
password as one of the parameters. You can send all parameters for the API call in the URL
as part of an HTTP GET, or you can use an HTTP POST to send the parameters.
For best performance, you should cache and/or store the data returned from the API calls in your
own system if the same data is going to be accessed repeatedly. While our servers can provide
the data in a transactional way, there is a lot of overhead in building up the response data
and then you having to parse that data to your own format. You will often find that retrieving
the data and storing it in a format more appropriate for your use on your own server will
achieve better performance than trying to make an API call to our server for every requested
page on your custom site.
The following section will document the actual API calls available.
API
This section will list each of the API calls available and have a brief description of the data
available from that call. Each API call is to a specific web page depending on the information
you are looking for, and every page accepts a variety of parameters. All of the calls
will expect the following parameters at a minimum (so they will not be described repeatedly
in the following sections):
Parameter | Description |
p | This is the password that has been set for API access on the Settings screen of the Team Website |
s | This is the sport the team website is for. Can be "baseball", "softball", "basketball", or "football" |
t | This is the Team Identifier as set when creating your team website. If your Team URL is http://iscorebasebal.com/myteam, then the Team Identifier is just the "myteam" part. |
In addition to the parameters that every API call expects, there are some optional parameters that
any API calls that deal with games can have passed in:
Parameter | Description |
lg | A comma separated list of leagues to filter to. This will filter the results to only games / statistics for games that were assigned to any of the league GUIDs passed in. |
games | A comma separated list of games. If you have identified a specific set of games you want returned, you can pass the GUIDs to this parameter. |
json | If you want a JSON formatted response instead of XML, pass json=1 to the request. The data will be formatted as a JSON object. It is transformed from XML to JSON using the PHP json_encode function of a SimpleXML object representation of the resulting XML |
Some of the API calls have additional parameters that can be passed in. For example, you may pass
in a Game or Player GUID to retrieve data for a specific game or player. Here are the API calls
that are available:
Get Team Roster
To retrieve the Team Roster for a team website, use the following call (replacing the parameters
with the appropriate values for the Team Website you are retrieving data for).
SAMPLE CALLS:
RESULT:
The TEAM element will have the following attributes:
Attribute | Description |
guid | Each team has a unique GUID that identifies the team |
name | This is the full name for the team |
shortName | This is a short name for the team --- used when space is limited |
manager | This is the name of the coach or manager as set in iScore |
teamColor | This is the RGB color selected for this team. It is in RRGGBB format (hex values for each) |
... | Depending on the sport, there may be additional attributes available like additional coaches or notes. By examining the XML any additional fields will become obvious |
There will be a PLAYER element for each player in the team roster with the following:
Attribute | Description |
guid | Each player has a unique GUID that identifies the player |
jersey | This is the jersey number for the player on this team |
firstName | First name of this player |
lastName | Last name of this player |
order | This is a number representing the order of the players in the roster (starting with 0) |
position | This is the position of the player and will depend on the sport. For example, with baseball, it will be the number representing the default position of the player (1=Pitcher, 2=Catcher, 3=First Base, etc) |
headshot | URL to use to retrieve the headshot for this Player. The URL will return a placeholder image if no image has been assigned to the player |
... | Depending on the sport, there may be additional attributes available for players such as throwing hand, batting hand, shooting hand, height, weight, reach, etc. By examining the XML any additional fields will become obvious |
Get Game Listing
To retrieve a Game Listing for a team website, use the following call (replacing the parameters
with the appropriate values for the Team Website you are retrieving data for).
SAMPLE CALLS:
RESULT:
The TEAM element will have the following attributes:
Attribute | Description |
guid | Each team has a unique GUID that identifies the team |
name | This is the full name for the team |
shortName | This is a short name for the team --- used when space is limited |
manager | This is the name of the coach or manager as set in iScore |
teamColor | This is the RGB color selected for this team. It is in RRGGBB format (hex values for each) |
wins | Count of number of wins for games returned for this team |
losses | Count of number of losses for games returned for this team |
ties | Count of number of ties for games returned for this team |
... | Depending on the sport, there may be additional attributes available like additional coaches or notes. By examining the XML any additional fields will become obvious |
There will be a GAME element for each game returned with the following attributes:
Attribute | Description |
guid | Each game has a unique GUID that identifies it |
name | Name that the scorekeeper set for this game |
start | Start date/time for this game (as Unix Timestamp) |
end | End date/time for this game (as Unix Timestamp) |
scheduled | Scheduled date/time for this game (as Unix Timestamp) |
visitor | Name of visitor team for this game |
home | Name of home team for this game |
result | Result of game (Win, Loss, or Tie) |
visitorScore | Score of the visiting team for this game |
homeScore | Score of the home team for this game |
hasScorecast | If an iScorecast is available for this game, this will be = "1" |
... | Depending on the sport, there may be additional attributes available for games. By examining the XML any additional fields will become obvious |
Get Game Statistics
To retrieve a list of statistics for a game, use the following call (replacing the parameters
with the appropriate values for the Team Website you are retrieving data for). By default, the call
will return all non-zero statistics for the players on this team. If you want to see even the
statistics that are zero for every player, you can pass the value "1" in the "all" parameter
(i.e. add "&all=1" to the HTTP GET URL, or pass all=1 as a parameter with an HTTP POST).
SAMPLE CALLS:
RESULT:
There will be a single GAME element representing the game stats are returned for:
Attribute | Description |
guid | GUID of the game the returned stats are for |
name | Name that the scorekeeper set for this game |
start | Start date/time for this game (as Unix Timestamp) |
end | End date/time for this game (as Unix Timestamp) |
scheduled | Scheduled date/time for this game (as Unix Timestamp) |
visitor | Name of visitor team for this game |
home | Name of home team for this game |
result | Result of game (Win, Loss, or Tie) |
visitorScore | Score of the visiting team for this game |
homeScore | Score of the home team for this game |
hasScorecast | If an iScorecast is available for this game, this will be = "1" |
The TEAM element will be for the team the call is for and have the following attributes:
Attribute | Description |
guid | GUID of the team the stats are being displayed for |
name | This is the full name for the team |
shortName | This is a short name for the team --- used when space is limited |
manager | This is the name of the coach or manager as set in iScore |
teamColor | This is the RGB color selected for this team. It is in RRGGBB format (hex values for each) |
There will be one PLAYER element for each player that played for the team having the following attributes:
Attribute | Description |
guid | GUID of the player the stats are for |
firstName | First name of the player the stats are for |
lastName | Last name of the player the stats are for |
jersey | Jersey number of the player on the team being requested |
...stats... | There will be a variety of stat fields returned. Click one of the samples to see the stats for each sport. Only non-zero values are returned by default. |
Get Leagues
Retrieves the set of Leagues a team is a member of. Leagues allow filtering of statistics calls
to summarize only games that took place in a partcular league.
SAMPLE CALLS:
RESULT:
There will be one LEAGUE element for each league defined on the scorekeeper's device:
Attribute | Description |
guid | GUID of the league |
name | Name of the league |
gameCount | Number of games for this team in this league |
Get Cumulative Statistics
To retrieve a list of cumulative statistics for all players on the team, use the following call
(replacing the parameters with the appropriate values for the Team Website you are retrieving data
for). You can also filter to only summarize for a subset of leagues by passing a parameter
"&lg=leagueGuid1,leagueGuid2,leagueGuid3..." where you have a comma separated list of any number
of League GUIDS you want to include in the results. You can also use the optional parameter
"&all=1" to show all stats - even those with 0 values. This should probably only be used when
you are trying to determine all the available stat fields for a sport.
SAMPLE CALLS:
RESULT:
The TEAM element will be for the team the call is for and have the following attributes:
Attribute | Description |
guid | GUID of the team the stats are being displayed for |
name | This is the full name for the team |
shortName | This is a short name for the team --- used when space is limited |
manager | This is the name of the coach or manager as set in iScore |
teamColor | This is the RGB color selected for this team. It is in RRGGBB format (hex values for each) |
There will be one PLAYER element for each player that played for the team having the following attributes:
Attribute | Description |
guid | GUID of the player the stats are for |
firstName | First name of the player the stats are for |
lastName | Last name of the player the stats are for |
jersey | Jersey number of the player on the team being requested |
...stats... | There will be a variety of stat fields returned. Click one of the samples to see the stats for each sport. Only non-zero values are returned by default. |
Get Detailed Player Statistics
To retrieve a list of detailed stats for all games a player has played in, use the following call
(replacing the parameters with the appropriate values for the Team Website you are retrieving data
for). The pg= parameter is the Player GUID you want the data for, and can be seen in many of the
other calls including the Team Roster call. You can filter to only games in a subset of leagues by
passing a parameter "&lg=leagueGuid1,leagueGuid2,leagueGuid3..." where you have a comma separated
list of any number of League GUIDS you want to include in the results. You can also use the optional
parameter "&all=1" to show all stats - even those with 0 values. This should probably only be used
when you are trying to determine all the available stat fields for a sport.
SAMPLE CALLS:
RESULT:
The PLAYER element will have the details for the player with the following attributes:
Attribute | Description |
guid | GUID of the player the stats are for |
firstName | First name of the player the stats are for |
lastName | Last name of the player the stats are for |
jersey | Jersey number of the player on the team being requested |
There will be one GAME for each game in the result with the following attributes:
Attribute | Description |
guid | GUID of the game the returned stats are for |
name | Name that the scorekeeper set for this game |
start | Start date/time for this game (as Unix Timestamp) |
end | End date/time for this game (as Unix Timestamp) |
scheduled | Scheduled date/time for this game (as Unix Timestamp) |
visitor | Name of visitor team for this game |
home | Name of home team for this game |
visitorScore | Score of the visiting team for this game |
homeScore | Score of the home team for this game |
result | Result of game (Win, Loss, or Tie) |
...stats... | There will be a variety of stat fields returned. Click one of the samples to see the stats for each sport. Only non-zero values are returned by default. |
Sample API Usage
A sample page has been created to show a simple AJAX call to the API using client side code only.
You can see that here:
http://api.iscorecentral.com/samplejson.html
If you create something worth showing off with the Team Website API, please let us know by
sending an email to support@iscoresports.com
and letting us know about it. We will post it here for others to see and learn from.
Terms of Use
The Team Website API requires an active Team Website in order to retrieve data.
If you plan to commercialize anything written against the API, email
us at support@iscoresports.com with a
brief explanation of what you intend to do. We can then make sure that our APIs can handle the
use case, and if it is something we feel other iScore users will be interested in, we can help
promote it as well.
(c) 2011 iScore Sports - All Rights Reserved
|