iScore Sports

Team Website API


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):

ParameterDescription
pThis is the password that has been set for API access on the Settings screen of the Team Website
sThis is the sport the team website is for. Can be "baseball", "softball", "basketball", or "football"
tThis 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:

ParameterDescription
lgA 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.
gamesA 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.
jsonIf 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:
    AttributeDescription
    guidEach team has a unique GUID that identifies the team
    nameThis is the full name for the team
    shortNameThis is a short name for the team --- used when space is limited
    managerThis is the name of the coach or manager as set in iScore
    teamColorThis 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:
    AttributeDescription
    guidEach player has a unique GUID that identifies the player
    jerseyThis is the jersey number for the player on this team
    firstNameFirst name of this player
    lastNameLast name of this player
    orderThis is a number representing the order of the players in the roster (starting with 0)
    positionThis 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)
    headshotURL 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:
    AttributeDescription
    guidEach team has a unique GUID that identifies the team
    nameThis is the full name for the team
    shortNameThis is a short name for the team --- used when space is limited
    managerThis is the name of the coach or manager as set in iScore
    teamColorThis is the RGB color selected for this team. It is in RRGGBB format (hex values for each)
    winsCount of number of wins for games returned for this team
    lossesCount of number of losses for games returned for this team
    tiesCount 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:
    AttributeDescription
    guidEach game has a unique GUID that identifies it
    nameName that the scorekeeper set for this game
    startStart date/time for this game (as Unix Timestamp)
    endEnd date/time for this game (as Unix Timestamp)
    scheduledScheduled date/time for this game (as Unix Timestamp)
    visitorName of visitor team for this game
    homeName of home team for this game
    resultResult of game (Win, Loss, or Tie)
    visitorScoreScore of the visiting team for this game
    homeScoreScore of the home team for this game
    hasScorecastIf 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:
    AttributeDescription
    guidGUID of the game the returned stats are for
    nameName that the scorekeeper set for this game
    startStart date/time for this game (as Unix Timestamp)
    endEnd date/time for this game (as Unix Timestamp)
    scheduledScheduled date/time for this game (as Unix Timestamp)
    visitorName of visitor team for this game
    homeName of home team for this game
    resultResult of game (Win, Loss, or Tie)
    visitorScoreScore of the visiting team for this game
    homeScoreScore of the home team for this game
    hasScorecastIf 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:
    AttributeDescription
    guidGUID of the team the stats are being displayed for
    nameThis is the full name for the team
    shortNameThis is a short name for the team --- used when space is limited
    managerThis is the name of the coach or manager as set in iScore
    teamColorThis 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:
    AttributeDescription
    guidGUID of the player the stats are for
    firstNameFirst name of the player the stats are for
    lastNameLast name of the player the stats are for
    jerseyJersey 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:
    AttributeDescription
    guidGUID of the league
    nameName of the league
    gameCountNumber 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:
    AttributeDescription
    guidGUID of the team the stats are being displayed for
    nameThis is the full name for the team
    shortNameThis is a short name for the team --- used when space is limited
    managerThis is the name of the coach or manager as set in iScore
    teamColorThis 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:
    AttributeDescription
    guidGUID of the player the stats are for
    firstNameFirst name of the player the stats are for
    lastNameLast name of the player the stats are for
    jerseyJersey 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:
    AttributeDescription
    guidGUID of the player the stats are for
    firstNameFirst name of the player the stats are for
    lastNameLast name of the player the stats are for
    jerseyJersey number of the player on the team being requested


    There will be one GAME for each game in the result with the following attributes:
    AttributeDescription
    guidGUID of the game the returned stats are for
    nameName that the scorekeeper set for this game
    startStart date/time for this game (as Unix Timestamp)
    endEnd date/time for this game (as Unix Timestamp)
    scheduledScheduled date/time for this game (as Unix Timestamp)
    visitorName of visitor team for this game
    homeName of home team for this game
    visitorScoreScore of the visiting team for this game
    homeScoreScore of the home team for this game
    resultResult 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