Overview

The ALPS API is protected on two fronts: both the application and user need to be authenticated. In order for applications and users to authenticate they will need to be registered. To register as a developer follow this link. Once you have registered as a developer, you'll be able to use the portal to register your application with this link. After your application has been registered, you'll get two values:

  1. Access Key
  2. Shared Secret

The access key serves to identify your application to the API. The shared secret used to generate a signature (see below) and should never be made publicly available. Ideally, the shared secret should not be human readable in your source code. Once you've used the shared secret to generate a signature you'll have two values: access key and signature. These values are used in every API call to authenticate your application, but not the user.

The user is authenticated via the login method, which returns a token to your application. Every other API method you call will require the combination of these three things, passed as a query string:

Value Query String Parameter Name Example Length Description
Access Key key f786504c72057d52360cd9c776b46693adbd3a90 40 characters Identifies your application to the API.
Shared Secret N/A - you never send it over the network 0HrepxVO4TqNYkZb4CeK7XntWtlUJPXwiMIW70gj 40 characters The secret key used to generate signature and identify/authenticate your application
Signature signature 45c0958a2102408a560083db26d239ff 32 characters represented as hexadecimals Authenticate your applications identity to the API, generated from the shared secret.
Token token cd55dc8ff2b20238030af9b0c4d9ec8e 32 characters Authenticate the user to the API, received from the login method.

The example query string to use with an API call is then:

?token=60ad5ebf9af741c8&signature=45c0958a2102408a560083db26d239ff&key=f786504c72057d52360cd9c776b46693adbd3a90

Generating The Signature

The API shared secret and the access key work together like a username and password for your application. The access key is like the username and the signature (generated from the shared secret) is like the password. In order to generate the signature, concatenate the following in the following order:

  1. the access key
  2. the shared secret
  3. the current unix time

then find the MD5 hash of that concatenated value.

Clock drift can be a problem since the API uses the current time to create the signature. To compensate, all signatures are valid for +/- 5 minutes from the time they're generated.

Below are some examples:

Generating A Signature With Python

# Get the function time from module time
from time import time
# Get the md5 object from module hashlib
from hashlib import md5
accessKey="f786504c72057d52360cd9c776b46693adbd3a90"
sharedSecret="0HrepxVO4TqNYkZb4CeK7XntWtlUJPXwiMIW70gj"
# Get the current time in seconds since epoch
currentTime = int(time())
# Concatenate them
stringToHash = "{0}{1}{2}".format(accessKey, sharedSecret,currentTime)
m = md5()
m.update(stringToHash)
signature = m.hexdigest()

Generating a Signature With Ruby

require 'digest/md5'
def getSignature(key,sharedSecret)
   concatString = [key,sharedSecret,Time.now.to_i].join("") #Concatenate in this order
   Digest::MD5.hexdigest(concatString) #return the MD5 Digest
end

Generating a Signature With Objective-C

# Get the function time from module time
-(NSString *) generateSignature:(NSString *)accessKey sharedSecret:(NSString *) theSharedSecret
{
          // concatenate the accessKey and signature and generate MD5 hash for the concatenated string
           NSString *signature = [[NSString stringWithFormat:@"%@%@%@", accessKey,theSharedSecret, getUnixTime] MD5];
           return signature;
}
 
 //generate MD5 hash from string
- (NSString*)MD5 {
	// Create pointer to the string as UTF8
	const char* ptr = [self UTF8String];
	// Create byte array of unsigned chars
	unsigned char md5Buffer[CC_MD5_DIGEST_LENGTH];
	// Create 16 byte MD5 hash value, store in buffer
	CC_MD5(ptr, strlen(ptr), md5Buffer);
	// Convert MD5 value in the buffer to NSString of hex values
	NSMutableString* output = [NSMutableString stringWithCapacity:CC_MD5_DIGEST_LENGTH * 2];
	for (int i = 0; i < CC_MD5_DIGEST_LENGTH; i++) {
		[output appendFormat:@"%02x",md5Buffer[i]];
	}
	return output;
}

Putting it All Together With A Simple Python Script

Here we put it all together with a simple Python script to show an example workflow:

# We like these libraries, feel free to use ones that you like.
from requests import post
from time import time
from hashlib import md5
import urllib
import json
 
# The access key you received when you registered your application.
accessKey = "f786504c72057d52360cd9c776b46693adbd3a90"
 
# The shared secret you received when you registered your application.
# N.B.  This should be kept secret, and shouldn't be human readable in your source code. We use it as a regular here for
#       the sake of clarity. Remember, this value is functions similarly to a password.
sharedSecret = "0HrepxVO4TqNYkZb4CeK7XntWtlUJPXwiMIW70gj"
 
# HTTP headers that are going to be used for every request. The API only accepts things of MIME type "application/json".
httpHeaders = {"Content-Type": "application/json"}
 
# This method generates the signature that is transmitted to authenticate your access key.
def generateSignature(accessKey, sharedSecret):
    # Get the current UNIX time.
    currentTime = int(time())
    # Concatenate:
    #   1. access key
    #   2. shared secret
    #   3. current unix time
    unHashedSignature = "{0}{1}{2}".format(accessKey, sharedSecret, currentTime)
    mdFiveHasher = md5();
    mdFiveHasher.update(unHashedSignature)
    # The signature that you'll actually send.
    signature = mdFiveHasher.hexdigest()
 
# This method logs into the API and returns a token that's valid for +/- five minutes from the time its generated.
def login(userName, password):
    # Create the payload for the login method.
    loginRequestDict = {"username": userName, "password": password}
    # Convert the dict to a JSON string.
    loginRequestPayload = json.dumps(loginRequestDict)
 
    # The base URL used to log into the API. (w/o query parameters)
    loginBaseUrl = "https://api.espnalps.com/login"
 
    queryParams = {
        # The access key that was generated when you registered your app
        "key": accessKey,
        # The signature generated from your shared secret, the current time, and access key
        "signature": generateSignature(accessKey, sharedSecret)
    }
 
    # The URL used to log into the API. (w/ query parameters)
    loginUrl = loginBaseUrl + "?" + urllib.urlencode(queryParams)
 
    # Actually make the API call to login
    response = post(loginUrl, headers = httpHeaders, data = loginRequestPayload)
 
    # Convert the JSON document to a python dictionary.
    responseDict = json.loads(response.content)
 
    # Return the token!
    responseDict["response"]["token"]
Comments

Introduction to OSIRIS

OSIRIS is a utility that we wrote to test the API ourselves but we believe that it will be just as useful to you for writing applications as it was to us. OSIRIS uses HTML5 features quite extensively, particularly the PushState feature to update the address bar without refreshing the page. It will definitely work in latest Google Chrome releases but we can't guarantee full functionality in other browsers. It is worth noting that the page may not look exactly as shown below as the tool evolves further but the underlying UI concepts will still be relevant.

Osiris-screen-components.png

Components

Taskbar

This is where the buttons for doing various tasks go

Button Task
Select App You can select the App so that the AccessKey and SharedSecret are updated in the interface.
Fix JSON Some of the examples in the wiki or elsewhere may not have proper JSON formatting, this provides a limited functionality to fix those. For more complicated JSON doctoring, we use http://jsonlint.com and we recommend it to you too.
Current Time Writing Timestamp by hand can be annoying, so this helper function lets you enter the current time in the required format.
Fill Template Fills the JSON template for the selected methodType if it's a POST or PUT request
Report Error Submit a bug report with the current information in the page, the output, your browser type, etc.

Method Details

Field Description
Server API server to connect to (most often https://api.espnalps.com)
Method Name Method Names are the API methods outlined in our Documentation
Path Parameters For GET methods and some PUT/POST methods, we require Path parameters ('/<gameId>' type parameters after the method name), you can put these here. You can append these Path parameters at the end of Method Name too but we don't recommend that for future compatibility reasons.
Method Type GET/POST/PUT/DELETE options. This is generally automatically selected when you choose a method name.
Access Key Your application's accesskey. This field can also be filled by selecting application from dialog made by the 'Select App' button too.
Shared Secret Your application's sharedSecret. This field can also be filled by selecting application from dialog made by the 'Select App' button too.

Payload

Enter your payload for POST/PUT requests. The editor supports rudimentary history Ctrl+Y, Ctrl+Z in modern browsers.

Response

The response you get from the server when you press Submit.

Using OSIRIS

When you press the Submit button, the URL will update to something like this

http://www.espnalps.com/portal/osiris?server=http://api.espnalps.com/prod&methodName=login/&methodType=POST&accessKey=89672bd22cc97a684f4b3135fd698cb92a567e1e&sharedSecret=hAFJOx2JxX0xwlp1X2WuSBH2YfPpnWcDkLaq9Nmf&token=a717684111e7cb01b41f707f06b7ed0f&payload=%7B%0A%20%22username%22%3A%20%22%22%2C%0A%20%22password%22%3A%20%22%22%0A%7D&arguments=

If you use this link in future, the fields in the site will be filled out for you. Apart from being extremely convenient, this lets us debug problems you may run into when using our API.

Comments


URL

https://api.espnalps.com/login?signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the Login method. Unlike other methods, a token doesn't need to be provided but if it is provided, it is ignored and if the user can login successfully, that token is rendered invalid and all subsequent requests must use the token generated by this method.

All communication to the login method must occur over secure HTTPS protocol.

Payload

A JSON document containing a username and the associated password.

Example

{
    username: "testuser",
    password: "secretPassword"
}

Field Definitions

Field Name Description
username A string containing a valid username
end A string containing the associated password for the username

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:47:21.132+0000",
    request: "login",
    result: "okay",
    response : {
       token: "cd55dc8ff2b20238030af9b0c4d9ec8e"
    }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.token A random 32 character hexadecimal string that associates the user and the application and must be used for all subsequent requests.

Sample

Python

For demonstration, we're using the requests module in python, you can also use urllib2. The step for generating signature is assumed to have been implemented in a generateSignature(key, sharedSecret) function. Python code for this function is available in Example section in Authentication. Python 2.5.x or higher is assumed.

from requests import post
import urllib
# the payload can be constructed using your favorite json library
userData = """
{ 
  "username": "testuser",
  "password": "secretPassword"
}"""
url="https://api.espnalps.com/login"
queryParams = {
"key": "PUT_ACCESS_KEY",
"signature": generateSignature(key, sharedSecret)
}
new_url = url + "?"+ urllib.urlencode(queryParams)
r = post(new_url, headers={"Content-Type": "application/json"}, data = userData)
print r.headers  
print r.content


Ruby

We're going to use the rest-client library to demonstrate the process but you're welcome to use other libraries for doing http requests (net/http is in the standard library). The code for generating signatures, the function getSignature(key,sharedSecret) are in Examples section in Authentication.

require 'rest_client'
require 'json'
url = "https://api.espnalps.com/login?key=%s&signature=%s"%[ACCESS_KEY,getSignature(ACCESS_KEY,SHARED_SECRET)]
userData = { "username" => "testUser", "password" => "testPassword."}
RestClient.post url, userData.to_json, :content_type => :json, :accept=> :json


Comments


RFC 3339 timestamp value

YYYY-MM-DDTHH:MM:SS.xxx[+/-]0000

example 2011-09-10T12:47:21.231-0500

Note the absence of semicolon for timezone.

where

  • YYYY is 4 digit year
  • MM is 2 digit month, left padded 1 is january
  • DD is a 2 digit day of month, left padded, 1 is first day of month
  • HH is a 24 hour clock value hour (0-23)
  • MM is the minute of the hour, 0-59
  • SS is the second of the minute, 0-59
  • xxx (number of xs is arbitrary) is an optional arbitrary sub-second timevalue (i.e. 3 digits for milliseconds, 6 digits for microseconds, etc). It should be accurate and consistent.
  • This is followed by a timezone indicator in the form of GMT offset, such as, -0500 for EST

Sample

Any C like language that has strftime should be able to generate and parse the timestamp.

Objective C

  • Parsing
NSDateFormatter* df = [[NSDateFormatter alloc]init];
[df setDateFormat:@"yyyy-MM-dd'T'HH:mm:ss.SSSZ"];
NSString* str = @"2012-01-13T09:14:26.368-0500";   
NSDate* date = [df dateFromString:str];

Python

Python stores a naive datetime object (without the timezone information) by default. And the strftime function in time module supports time_struct that doesn't have microsecond information in it. However, the datetime object does have that information. So, if you want to create a complete timestamp to send us in python using just the standard libraries, this is what you need to do.

  • Generating
import datetime, time
time.tzset() #Set the timezone from OS
datetime.datetime.now().strftime('%Y-%m-%dT%H:%M:%S.%f')[:-3]+time.strftime("%z")
  • Parsing

Since we are always going to reply back in UTC time, datetime module would suffice to parse after removing timezone. For consistency, we'll use -0500 in the example below for timezone.

from datetime import datetime
dateString = "2012-01-13T09:14:26.368-0500"
datetime.strptime(dateString[:-5], "%Y-%m-%dT%H:%M:%S.%f")

Ruby

  • Generating
Time.now.strftime("%Y-%m-%dT%H:%M:%S.%L%z")
  • Parsing
require 'date'
Date.strptime("2012-01-13T09:14:26.368-0500","%Y-%m-%dT%H:%M:%S.%L%z").to_time

Comments


Basic Error Response

Example Error

The basic format for an error response looks like:

{
    time: " 2011-09-10T12:47:21.231-0000",
    request: "login",
    result: "error",
    errors: [
        {
            field: "password",
            type: "INVALID",
            message: "The password must be at least six characters."
        }
    ]
}

Field Definitions

Field Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result A string containing "error".
errors An array of either JSON objects or strings detailing the errors encountered.

The "errors" field

Note: The "errors" field will contain a description for each error encountered in the submitted document. So if two fields were invalid then there will be two JSON objects in this array.

Field Errors

If there is a problem with one of the fields in the JSON document submitted via a POST method the array referenced by the "errors" field will contain a JSON document that looks like:

{
    field: "password",
    type: "INVALID",
    message: "The password must be at least six characters."
}

Where:

Field Field Description
field The name of the field that caused the error (was invalid).
type A string that is one of: INVALID, MISSING, BAD_DATA. See below.
message An error message describing why the field was invalid.

The different values for the "type" field are:

Error Type Description Example
INVALID The data provided could not be validated. Providing a string when an integer is required.
MISSING The field was required, but could not be found in the submitted document. Submitting any event document without a context sub-document.
BAD_DATA The data provided was valid (type-wise) but was bad for some other reason. Submitting a PlayerId that doesn't match any player in the database.

Other Errors

For non-field errors, the "errors" field will contain a string describing the error.

Example

{
    time: " 2011-09-10T12:47:21.231-0500",
    request: "login",
    result: "error",
    errors: [ "The server encountered an internal error." ]     
}

Comments


The context document contains a timestamp of when the event occurred, the home team score, and the away team score.

Example Document

context: {
     time: "2011-09-10T12:47:21.231-0500",
     homeScore: 17, 
     awayScore: 5
}

Field Definitions

Field Name Required/Optional Field Description
time Required A valid timestamp of when the event occurred.
homeScore Required The home team's score.
awayScore Required The away team's score.
Comments

A 2 integer array representing the field location from where the logged event took place. The first integer is the x-coordinate, the second is the y-coordinate. The top left corner of the Lacrosse field, oriented such that the team benches would be on the bottom of the image, is the origin or (0,0). The x-coordinate should be between 0 and 330 inclusive. The y-coordinate should be between 0 and 180 inclusive.

LacrosseFieldDimensions.png

If you want to use the image in your application, you can download a higher resolution image from http://www.espnalps.com/images/LacrosseField.png, we hold the copyrights to this image but you are free to use it in your application.

Comments


Description

The games method takes a time range specified by two timestamps, and returns all of the "Games" that have occurred or will occur within that time frame.

URL

http://api.espnalps.com/v0/clx/games?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing a start date and end date representing the time window for which you want a list of scheduled games.

Example

{
    start: "2011-09-10T12:47:21-0500",
    end: "2011-09-11T12:47:21-0500"
}

Field Definitions

Field Name Description
start A string containing a valid timestamp
end A string containing a valid timestamp

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:47:21.132+0000",
    request: "games",
    result: "okay",
    response : {
        games: [
            {
                gameId: "47cc67093475061e3d95369d",
                homeTeam: {
                    teamId: "5eea69ce03648afad283536e",
                    teamName: "Hometown LAX"
                },
                awayTeam: {
                    teamId : "4eea69ce03648afad2835373",
                    teamName: "Adversary Academy"
                },
                venue: "Practice Field",
                time: "2011-09-10T19:00:00+0000"
            }, 
            ...
        ]
    }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.games A complete list of the games, maintained in the administration module, scheduled to start within the start and end times provided in the request.

Each object in the array stored under "games" has the following field definitions:

Field Name Field Description
gameId The unique id for each game. Each game is comprised of a home team, an away team, a venue, and a scheduled start time.
homeTeam Each home team is comprised of a unique id and a home team name.
homeTeam.teamId The unique id for the home team.
homeTeam.teamName The home team name maintained within the administration module.
awayTeam Each away team is comprised of a unique id and an away team name.
awayTeam.teamId The unique id for the away team.
awayTeam.teamName The away team name maintained within the administration module.
venue The stadium or field name where the game is scheduled to occur.
time The scheduled start time for the game. The timestamp will include a '+/-HH:HH' component which is the GMT offset for the time zone applicable for the time stamp (game location).

For example: If the local time zone is eastern standard time (GMT-5) and the time locally is 08/03/2011 12:58:32 then the properly formatted time stamp is: 08/03/2011 17:58:32 '-0500'


Comments


Description

The getGameData method takes a valid gameId and returns the home and away teamId's, team names, playerId's, names and jersey numbers. The data necessary to enable game set up in a scoring application. If setup data for the same gameId, appKey, and Token exists in the database, this data will also be returned as part of the response along with any event data successfully submitted for the game.

URL

http://api.espnalps.com/v0/clx/getGameData/[gameId]?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

The values in red are API path parameters. In this case they are:

Parameter name Parameter Description
gameId The gameId identifying the the game you want data for.

Response

The getGameData response will include an array of data as maintained in the administration module related to the home team, and an array of data related to the away team. This data will be used to enable game setup.

{
    homeTeam: {
        teamId: "4eea69ce03648afad2835365",
        teamName: "Ace Academy",
        players: [
            {
                playerId: "4eea69ce03648afad2835366",
                name: {
                    firstName: "Name",
                    middleName: "Name",
                    lastName: "Name"
                },
                jerseyNumber: 1,
                isTeamPlayer: false
            }, 
            ...
        ]
    },
    awayTeam: {
        teamId: "4eea69ce03648afad2835367",
        teamName: "Rival University",
        players: [
            {
                playerId: "4eea69ce03648afad2835368",
                name: {
                    firstName: "Name",
                    middleName: "Name",
                    lastName: "Name"
                },
                jerseyNumber: 1,
                isTeamPlayer: false
            }, 
            ...
        ]
    },
    gameSetupData: {
        homeTeam: {
            onField: [ "4eea69ce03648afad2835366", ... ],
            goalie: "4eea69ce03648afad2835375"
        },
        awayTeam: {
            onField: [ "4eea69ce03648afad2835368", ... ],
            goalie: "4eea69ce03648afad2835374"
        },
        events: [
            {
                event: "periodstart",
                eventId: "4eea69ce03648afad283536d"
                gameId: "4eea69ce03648afad2835396", 
                period: 4,
                context: {
                    time: "2011-09-10T12:48:21.231-0000",
                    homeScore: 0,
                    awayScore: 0
                }
            }, 
            ...
        ]
    }
}

Field Definitions

Field Name Field Description
homeTeam Each home team is comprised of a teamId, a teamName, players and playerId(s), names(s) and jerseyNumber(s).
homeTeam.teamId The unique Id for the home team.
homeTeam.teamName The home team name maintained in the administration module.
homeTeam.players An array of player data for all of the players on the home team roster.
homeTeam.players.playerID For each player, the unique id for that player.
homeTeam.players.name An array containing the first, middle and last names of each player.
homeTeam.players.name.firstName The first name of the player as maintained in the administration module.
homeTeam.players.name.middleName The middle name of the player as maintained in the administration module.
homeTeam.players.name.lastName The last name of the player as maintained in the administration module.
homeTeam.players.jerseyNumber The jersey number recorded for the player in the administration module.
homeTeam.players.isTeamPlayer A true/false indicator identifying if the specific playerId represents the entire team to enable recording of ‘In Home’ penalties and ‘Team Turnovers’.
awayTeam Each away team is comprised of a teamId, a teamName, and players, playerId(s), names(s) and jerseyNumber(s).
awayTeam.teamId The unique id for the away team.
awayTeam.teamName The away team name maintained within the administration module.
awayTeam.players An array of player data for all of the players on the away team roster.
awayTeam.players.playerID For each player a unique id for that player.
awayTeam.players.name An array containing the first, middle and last names of each player.
awayTeam.players.name.firstName The first name of the player as maintained in the administration module.
awayTeam.players.name.middleName The middle name of the player as maintained in the administration module.
awayTeam.players.name.lastName The last name of the player as maintained in the administration module.
awayTeam.players.jerseyNumber The jersey number recorded for the player in the administration module.
awayTeam.players.isTeamPlayer A true/false indicator identifying if the specific playerId represents the entire team to enable recording of ‘In Home’ penalties and ‘Team Turnovers’.

If game setup data has already been stored in the database for this same gameId, appKey, and Token, the game setup data and any recorded game event data will be returned.

Field Name Field Description
gameSetUp The game set up data submitted in the setGameData document if posted successfully.
homeTeam The data set up regarding home team will be returned if the setGameData was posted successfully.
homeTeam.onField An array of playerId(s) representing the 10 on field players for the home team.
homeTeam.goalie The playerId identified as the goalie for the home team.
awayTeam The data set up regarding away team on field players will be returned if the setGameData was posted successfully.
awayTeam.onField An array of playerId(s) representing the 10 on field players for the away team.
awayTeam.goalie The playerId identified as the goalie for the away team.
gameEvents The complete set of events posted for the subject game by the user in the order of submission.
gameEvents.event For each event, the type of event posted.
gameEvents.eventId The unique identifier for the event.
gameEvents.gameId The gameId of the game being scored.
gameEvents….. The game event data originally submitted in the corresponding event document.



Comments



Description

The setGameData method posts the game setup data, each teams starting roster and the designated goalie player ID, to the database as it was entered by the app user. In the event the app crashes, or the user logs out of the app, and that same user, on the same app, logins in and selects the same game to score, the getGameData method will return the posted setup data at the end of the getGameData response to facilitate game setup for the user.

URL

http://api.espnalps.com/v0/clx/setGameData/[game id]?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

The value in red is the game id identifying the game you want to submit data for.

Payload

A JSON document detailing the game setup data entered before scoring starts.

Example

{
    time : "2011-09-10T12:47:21.231-0500",
    homeTeam : {
        onField: [
            "4eea69ce03648afad2835365",
            "4eea69ce03648afad2835366",
            "4eea69ce03648afad2835367",
            "4eea69ce03648afad2835368",
            "4eea69ce03648afad2835369",
            "4eea69ce03648afad283536a",
            "4eea69ce03648afad283536b",
            "4eea69ce03648afad283536c",
            "4eea69ce03648afad283536d",
            "4eea69ce03648afad283536e"
        ],
        goalie: "4eea69ce03648afad283536f"
    },
    awayTeam: {
        onField: [
            "4eea69ce03648afad2835370",
            "4eea69ce03648afad2835371",
            "4eea69ce03648afad2835372",
            "4eea69ce03648afad2835373",
            "4eea69ce03648afad2835374",
            "4eea69ce03648afad2835375",
            "4eea69ce03648afad2835376",
            "4eea69ce03648afad2835377",
            "4eea69ce03648afad2835378",
            "4eea69ce03648afad2835379"
        ],
        goalie: "4eea69ce03648afad283537a"
    }
}

Field Definitions

Field Name Field Description
time The time this user has started scoring the game.
homeTeam A document containing a list of players from the home team who are playing and who the goalie is.
homeTeam.onField An array containing the player ids of all the players who are playing for the home team.
homeTeam.goalie The player id of the player who is the goalie for the home team.
awayTeam A document containing a list of players from the away team who are playing and who the goalie is.
awayTeam.onField An array containing the player ids of all the players who are playing for the away team.
awayTeam.goalie The player id of the player who is the goalie for the away team.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

 {
    time: "2011-09-10T12:47:21.251+0000",
    request: "setGameData",
    result: "okay",  
    response: { gameId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.gameId The unique game identifier of successfully submitted game.

Comments


Description

The gameEnd method is used to indicate the end of the game and the termination of submission of game scoring events. The context data sent as part of gameEnd should contain the final score.

URL

http://api.espnalps.com/v0/clx/gameEnd?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the game identifier which will indicate the end of the game.

Example

 
{
    gameId: "4eea69ce03648afad2835365",
    context: {
        time: "2011-09-10T15:47:21.231-0500",
        homeScore: 12,
        awayScore: 6
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required The unique identifier for the game the user is currently scoring.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-12-09T12:15:01+0000",
    request: "gameEnd",
    result: "okay",  
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

</syntaxhighlight>

Comments


Description

The faceoff method is used to post the players involved and the winner of faceoff events that occur at the start of a quarter and after each goal.

URL

http://api.espnalps.com/v0/clx/faceoff?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the home and away playerId (s) participating in the faceoff, the winning playerId involved in the faceoff, the field location of the faceoff, and a properly formatted context document.

Example

{
    gameId: "5ffa23ce03648afad2812865",
    homePlayer: "4eea69ce03648afad2835365",
    awayPlayer: "4eea69ce03648afad283536b",
    winner: "4eea69ce03648afad2835365",
    location: [323, 152],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 3,
        awayScore: 1
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
homePlayer Required Unique playerId from the on field, home team roster, representing the home team player involved in the faceoff.
awayPlayer Required Unique playerId from the on field, away team roster, representing the away team player involved in the faceoff.
winner Required The unique playerId representing the home or away team player who won the faceoff by securing the ball for his team. Must be either the homePlayer or awayPlayer, identified above, as participating in the faceoff.
location Required The field location where the the faceoff occurred.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "faceoff",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The periodStart method is used to indicate the start of the period.

URL

http://api.espnalps.com/v0/clx/periodStart?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the period that is starting and the unique identifier for the game. Indicates the start of the specified period in the game.

Example

{
    gameId: "4eea69ce03648afad2835396",
    period: 4,
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 0,
        awayScore: 0
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
period Required Must be a positive integer 1-n identifying the period starting to be scored.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "periodStart",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The periodEnd method is used to indicate the end of the period.

URL

http://api.espnalps.com/v0/clx/periodEnd?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the period that is ending and the unique identifier for the game, indicating the end of the specified period in the game.

Example

{
    gameId: "4eea69ce03648afad2835395",
    period: 3,
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 6,
        awayScore: 5
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
period Required Must be a positive integer 1-n identifying the period that is ending.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "periodEnd",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The shot method is used to post the details surrounding a missed shot or attempt to score.


URL

http://api.espnalps.com/v0/clx/shot?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the playerId of the player who took the shot, the playerId of the defending goalie, the playerId of the blocker (optional field), the type of release when the ball left the corsse, the 'flight path' of the ball, the shot result, a true/false indicator identifying if possession was retained by the shooting team, the field location where the player took the shot and a properly formatted context doc.

Example

{
    gameId: "5ffa23ce03648afad2812865",
    shooter: "4eea69ce03648afad2835381",
    goalie: "4eea69ce03648afad2835390",
    blocker: "4eea69ce03648afad2835389",
    releaseType: "low-to-high",
    flight: "air",
    shotResult: "blocked",
    possession: true,
    location: [199, 12],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 4,
        awayScore: 2
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
shooter Required The playerId, representing the player taking the shot.
goalie Required The playerId of the opposing team goalie who was guarding the net at the time of the shot.
blocker Optional The playerId of the opposing team player who blocked the shot, if applicable.
releaseType Optional A text string representing the type of shot taken. Must be one of: "low-to-high", "high-to-low", or "lateral".
flight Optional A text string representing the flight of the ball once released from the crosse. Valid values are "bounce" or "air".
shotResult Required A text string representing the result of the shot taken. Valid values are "blocked", "saved", "high", "post", "wideR", or "wideL". (Note shots resulting in goals should send a 'goal' document.)
possession Required A true/false indicator to represent whether the shooting team retains possession after the shot.
location Required The field location where the shot was taken.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:47:21.231+0000",
    request: "shot",
    result: "okay",
    response : { eventId: "47cc67093475061e3d95369d" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response The event id referencing the this event in the database.

Comments


Description

The substitution method is used to record a substitution, a bench player relieving an on field player.

URL

http://api.espnalps.com/v0/clx/substitution?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the playerId of the on field player designated as leaving the field (subbing out), and the playerId for the player from the bench, going onto the field, and a properly formatted context document.

Example

{
    gameId: "4eea69ce03648afad283891a",
    exitingPlayer: "4eea69ce03648afad2835365",
    enteringPlayer: "4eea69ce03648afad283537a",
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 6,
        awayScore: 4
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
exitingPlayer Required Unique identifier from the on field roster, representing the player leaving the field on a substitution.
enteringPlayer Required Unique identifier of a player from the team roster, representing the player entering the field on a substitution.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

 {
    time: " 2011-09-10T12:47:21.231+0000",
    request: "substitution",
    result: "okay",  
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The turnover method is used to record a change in possession.

URL

http://api.espnalps.com/v0/clx/turnover?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the unique playerId of the player who committed the turnover, the playerId of the player on the opposing team who forced the turnover, if applicable, the field location where the turnover occurred and a properly formatted context document

Example

{
    gameId: "5ffa23ce03648afad2812865",
    committedBy: "4eea69ce03648afad2835365",
    forcedBy: "4eea69ce03648afad2835366",
    location: [223, 56],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 1,
        awayScore: 0
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
committedBy Required The playerId identifying for the player committing the turnover. Team turnovers should use the playerId which represents the team and not an individual player. Team turnovers cannot be forced.
forcedBy Optional The playerId identifying the player who forced the turnover. Not all turnovers are forced.
location Required The field location where the turnover occurred.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

 {
    time: "2011-09-10T12:47:21.231+0000",
    request: "turnover",
    result: "okay",  
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The goal method is used to post the details related to a successful shot, or score.

URL

http://api.espnalps.com/v0/clx/goal?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the playerId of the player who scored the goal, the playerId of the defending goalie, the release type (such as high-to-low), the flight of the ball, (whether it bounced to the net or was thrown), the playerId of the assissting player, the field location where the shot was taken and a properly formatted context document. Release type, flight and assissting player are all optional fields.

Example

{
    gameId: "5ffa23ce03648afad2812865",
    shooter: "4eea69ce03648afad2835365",
    goalie: "4eea69ce03648afad2835389",
    releaseType: "low-to-high",
    flight: "air", 
    assistedBy: "4eea69ce03648afad2835388",
    location: [323, 12],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 7,
        awayScore: 2
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
shooter Required The playerId, representing the player taking the shot.
goalie Required The playerId of the opposing team goalie who was guarding the net at the time of the shot.
releaseType Optional A text string representing the direction of the ball at the time the shot is taken. Valid values are "low-to-high", "high-to-Low", and "lateral".
flight Optional A text string representing the path the ball takes after being thrown. Valid values are either "bounce" or "air".
assisstedBy Optional The playerId representing the player who assisted in making the goal. Not all goals are assisted.
location Required The field location where the the shot was taken.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "goal",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The groundBallPickup method is used to indicate the player who gained possession of a contested ball for his team.

URL

http://api.espnalps.com/v0/clx/groundBallPickup?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the playerId of the player who picked up the ground ball, the field location where the pickup occurred and a properly formatted context document.

Example

{
    gameId: "5ffa23ce03648afad2812865",
    pickedUpBy: "4eea69ce03648afad283537a",
    location: [173, 62],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 12,
        awayScore: 6
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
pickedUpBy Required The unique playerId for the player who picked up the loose ball.
location Required The field location where the pickup occurred.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "groundBallPickup",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The penalty method is used to submit the player id, penalty type and duration.

URL

http://api.espnalps.com/v0/clx/penalty?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the gameId, the playerId of the player who committed the penalty, the playerId of the member of the opposing team who drew the penalty, the type of penalty, the length of the penalty, the field location where the penalty occurred and a properly formatted context document.

Example

{
    gameId: "5ffa23ce03648afad2812865",
    committedBy:  "4eea69ce03648afad283536c",
    drewBy: "4eea69ce03648afad2835371",
    penaltyType: "cross-check",
    penaltyLength: 30,
    location: [323, 75],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 1,
        awayScore: 2
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
committedBy Required The unique identifier for the player who committed the penalty.
drewBy Optional The unique identifier for the player who drew the penalty.
penaltyType Required A text field representing the type of penalty incurred. Must be one of "cross-check", "illegal-body-check", "illegal-crosse", "illegal-equipment", "slashing", "tripping", "unnecessary-roughness", "unsportsmanlike-conduct", "fighting", "flagrant-misconduct", "crease-violation/goalkeeper-interference", "holding", "illegal-offensive-screening", "illegal-procedure", "conduct-foul", "interference", "offside", "pushing", "stalling", "warding-off", "withholding-ball-from-play", "targeting-the-head-and-neck".
penaltyLength Required A positive integer representing the duration of the penalty in seconds. Penalties that result in an award of the ball to the other team and no time served should not send a penaltyLength field. Valid penalty times are 0, 30, 60, 120, and 180, representing the time being served in seconds. Penalties that are addressed by awarding of the ball to the other team and 0 seconds served, should also send a Turnover document.
location Required The field location where the penalty occurred.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "penalty",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The penaltyRelease method is used to indicate players who have been released from the penalty box and are returning to the field.

URL

http://api.espnalps.com/v0/clx/penaltyRelease?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the playerId of the player being released from serving time in the penalty box and a properly formatted context document.

Example

{
    gameId: "5ffa23ce03648afad2812865",
    releasedPlayer: "4eea69ce03648afad2835381",
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 6,
        awayScore: 4
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
releasedPlayer Required Unique identifier of the player in the penalty box being released and returning to the field of play.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "penaltyRelease",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The clearAttempt method is used to record successful and failed attempts to clear the ball out of the defensive zone.

URL

http://api.espnalps.com/v0/clx/clearAttempt?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the playerId of the player who attempted to clear the ball from his defensive end, a true/false indicator identifying if the clear attempt was successful or not, the field location where the clear attempt ended and a properly formatted context document.

Example

{
    gameId: "5ffa23ce03648afad2812865",
    attemptedBy: "4eea69ce03648afad2835365",
    cleared: true,
    location: [323, 12],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 12,
        awayScore: 6
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
attemptedBy Required The playerId who attempted to clear the ball from within their defensive end of the field.
cleared Required A true/false indicator to represent whether the clearing attempt was successful or not.
location Required The field location where the clear attempt ended.
context Required A valid context subdocument.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

 {
    time: "2011-09-10T12:47:21.251+0000",
    request: "clearAttempt",
    result: "okay",  
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The deleteEvent method can be used to delete a scoring event from the database. In order to allow an app user to correct for erroneously entered data, the incorrect eventId should be deleted and a new event, of the appropriate type, inserted.

URL

http://api.espnalps.com/v0/clx/deleteEvent/[event id]?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

The value in red is the event id of the event you wish to delete.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

 {
    time: " 2011-09-10T12:47:21.231+0000",
    request: "deleteEvent",
    result: "okay",  
    response: { deletedEvent: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.deletedEvent The unique event identifier of the deleted event.

Comments


The context document contains a timestamp of when the event occurred, the home team score, and the away team score.

Example Document

context: {
     time: "2011-09-10T12:47:21.231-0500",
     homeScore: 17, 
     awayScore: 5
}

Field Definitions

Field Name Required/Optional Field Description
time Required A valid timestamp of when the event occurred.
homeScore Required The home team's score.
awayScore Required The away team's score.
Comments



A 2 integer array representing the court location where the logged event occurred. The first integer is the x-coordinate, the second is the y-coordinate. The top left corner of the court, oriented such that the team benches would be on the bottom of the image, is the origin or (0,0). The x-coordinate should be between 0 and 940 inclusive. The y-coordinate should be between 0 and 500 inclusive.

BasketballCourtDimensions.png

If you want to use the image in your application, you can download a higher resolution image from http://www.espnalps.com/images/BasketballCourt.png, we hold the copyrights to this image but you are free to use it in your application.

Comments


Description

The games method takes a time range specified by two timestamps, and returns all of the "Games" that have occurred or will occur within that time frame.

URL

http://api.espnalps.com/{version}/basketball/{league}/games?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing a start date and time and an end date and time representing the time window for which you want a list of scheduled games.

Example

{
    start: "2011-09-10T12:47:21-0500",
    end: "2011-09-11T12:47:21-0500"
}

Field Definitions

Field Name Description
start A string containing a valid timestamp
end A string containing a valid timestamp

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:47:21.132+0000",
    request: "games",
    result: "okay",
    response : {
        games: [
            {
                gameId: "47cc67093475061e3d95369d",
                homeTeam: {
                    teamId: "5eea69ce03648afad283536e",
                    teamName: "Rival University"
                },
                awayTeam: {
                    teamId : "4eea69ce03648afad2835373",
                    teamName: "Academy of Science"
                },
                venue: "Arena 6",
                time: "2011-09-10T19:00:00+0000"
            }, 
            ...
        ]
    }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.games A complete list of the games, maintained in the administration module, scheduled to start within the start and end times provided in the request.

Each object in the array stored under "games" has the following field definitions:

Field Name Field Description
gameId The unique id for each game. Each game is comprised of a home team, an away team, a venue, and a scheduled start time.
homeTeam Each home team is comprised of a unique id and a home team name.
homeTeam.teamId The unique id for the home team.
homeTeam.teamName The home team name maintained within the administration module.
awayTeam Each away team is comprised of a unique id and an away team name.
awayTeam.teamId The unique id for the away team.
awayTeam.teamName The away team name maintained within the administration module.
venue The stadium or field name where the game is scheduled to occur.
time A properly formatted timestamp for the scheduled start time for the game.


Comments


Description

The getGameData method takes a valid gameId and returns the home and away teamId's, team names, playerId's, names and jersey numbers. The data necessary to enable game set up in a scoring application. If setup data for the same gameId, appKey, and Token exists in the database, this data will also be returned as part of the response along with any event data successfully submitted for the game.

URL

http://api.espnalps.com/{version}/basketball/{league}/getGameData/[Game Id]?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

The values in red are API path parameters. In this case they are:

Parameter name Parameter Description
Game Id The gameId identifying the the game you want data for.

Response

The getGameData response will include an array of data as maintained in the administration module related to the home team, and an array of data related to the away team. This data will be used to enable game setup.

{
    homeTeam: {
        teamId: "4eea69ce03648afad2835365",
        teamName: "Hometown Slammers",
        players: [
            {
                playerId: "4eea69ce03648afad2835366",
                name: {
                    firstName: "Name",
                    middleName: "Name",
                    lastName: "Name"
                },
                jerseyNumber: 1,
                isTeamPlayer: false
            }, 
            ...
        ]
    },
    awayTeam: {
        teamId: "4eea69ce03648afad2835367",
        teamName: "Fighting Wolverines",
        players: [
            {
                playerId: "4eea69ce03648afad2835368",
                name: {
                    firstName: "Name",
                    middleName: "Name",
                    lastName: "Name"
                },
                jerseyNumber: 1,
                isTeamPlayer: false
            }, 
            ...
        ]
    },
    gameSetupData: {
        homeTeam: {
            onField: [ "4eea69ce03648afad2835366", ... ],
        },
        awayTeam: {
            onField: [ "4eea69ce03648afad2835368", ... ],
        },
        gameEvents: [
            {
                event: "periodstart",
                eventId: "4eea69ce03648afad283536d"
                gameId: "4eea69ce03648afad2835396", 
                period: 4,
                context: {
                    time: "2011-09-10T12:48:21.231-0000",
                    homeScore: 0,
                    awayScore: 0
                }
            }, 
            ...
        ]
    }
}

Field Definitions

Field Name Field Description
homeTeam Each home team is comprised of a teamId, a teamName, players and playerId(s), playerName(s) and jerseyNumber(s).
homeTeam.teamId The unique Id for the home team.
homeTeam.teamName The home team name maintained in the administration module.
homeTeam.players An array of player data for all of the players on the home team roster.
homeTeam.players.playerID For each player, the unique id for that player.
homeTeam.players.name An array containing the first, middle and last names of each player.
homeTeam.players.name.firstName The first name of the player as maintained in the administration module.
homeTeam.players.name.middleName The middle name of the player as maintained in the administration module.
homeTeam.players.name.lastName The last name of the player as maintained in the administration module.
homeTeam.players.jerseyNumber The jersey number recorded for the player in the administration module.
homeTeam.players.isTeamPlayer A true/false indicator identifying if the specific playerId represents the entire team to enable recording of Administrative Technical Fouls.
awayTeam Each away team is comprised of a teamId, a teamName, and players, playerId(s), playerName(s) and jerseyNumber(s).
awayTeam.teamId The unique id for the away team.
awayTeam.teamName The away team name maintained within the administration module.
awayTeam.players An array of player data for all of the players on the away team roster.
awayTeam.players.playerID For each player a unique id for that player.
awayTeam.players.name An array containing the first, middle and last names of each player.
awayTeam.players.name.firstName The first name of the player as maintained in the administration module.
awayTeam.players.name.middleName The middle name of the player as maintained in the administration module.
awayTeam.players.name.lastName The last name of the player as maintained in the administration module.
awayTeam.players.jerseyNumber The jersey number recorded for the player in the administration module.
awayTeam.players.isTeamPlayer A true/false indicator identifying if the specific playerId represents the entire team to enable recording of Administrative Technical Fouls.

If game setup data has already been stored in the database for this same gameId, appKey, and Token, the game setup data and any recorded game event data will be returned.

Field Name Field Description
gameSetUp The game set up data submitted in the setGameData document if posted successfully.
homeTeam The data set up regarding home team will be returned if the setGameData was posted successfully.
homeTeam.onField An array of playerId(s) representing the 5 starting players for the home team.
awayTeam The data set up regarding away team players will be returned if the setGameData was posted successfully.
awayTeam.onField An array of playerId(s) representing the 5 starting players for the away team.
gameEvents The complete set of events posted for the subject game by the user in the order of submission.
gameEvents.event For each event, the type of event posted.
gameEvents.eventId The unique identifier for the event.
gameEvents.gameId The gameId of the game being scored.
gameEvents….. The game event data originally submitted in the corresponding event document.


Comments


Description

The setGameData method is used to update the database with the starting roster after game set up has been completed on the app.

URL

http://api.espnalps.com/{version}/basketball/{league}/setGameData/[game id]?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.


The value in red is the game id identifying the game you want to submit data for.

Payload

A JSON document detailing the game setup data entered before scoring starts.

Example

{
    time : "2011-09-10T12:47:21.231-0500",
    homeTeam : {
        onField: [
            "4eea69ce03648afad2835365",
            "4eea69ce03648afad2835366",
            "4eea69ce03648afad2835367",
            "4eea69ce03648afad2835368",
            "4eea69ce03648afad2835369"
        ],
    },
    awayTeam: {
        onField: [
            "4eea69ce03648afad2835375",
            "4eea69ce03648afad2835376",
            "4eea69ce03648afad2835377",
            "4eea69ce03648afad2835378",
            "4eea69ce03648afad2835379"
        ],
    }
}

Field Definitions

Field Name Field Description
time The time this user has started scoring the game.
homeTeam A document containing a list of players from the home team who are playing.
homeTeam.onField An array containing the player ids of all the players who are playing for the home team.
awayTeam A document containing a list of players from the away team who are playing.
awayTeam.onField An array containing the player ids of all the players who are playing for the away team.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

 {
    time: "2011-09-10T12:47:21.251+0000",
    request: "setGameData",
    result: "okay",  
    response: { gameId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.gameId The unique game identifier of successfully submitted game.


Comments


Description

The gameEnd method is used to indicate the end of the game and the termination of submission of game scoring events. The context data sent as part of gameEnd should contain the final score.

URL

http://api.espnalps.com/{version}/basketball/{league}/gameEnd?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the game identifier which will indicate the end of the game.

Example

 
{
    gameId: "4eea69ce03648afad2835365",
    context: {
        time: "2011-09-10T15:47:21.231-0500",
        homeScore: 88,
        awayScore: 76
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required The unique identifier for the game the user is currently scoring.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-12-09T12:15:01+0000",
    request: "gameEnd",
    result: "okay",  
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments



Description

The periodStart method is used to indicate the start of the period.

URL

http://api.espnalps.com/{version}/basketball/{league}/periodStart?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the period that is starting and the unique identifier for the game. Indicates the start of the specified period in the game.

Example

{
    gameId: "4eea69ce03648afad2835396",
    period: 2,
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 66,
        awayScore: 75
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
period Required Must be a positive integer 1-n identifying the period starting to be scored.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "periodStart",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The periodEnd method is used to indicate the end of the period.

URL

http://api.espnalps.com/{version}/basketball/{league}/periodEnd?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the period that is ending and the unique identifier for the game, indicating the end of the specified period in the game.

Example

{
    gameId: "4eea69ce03648afad2835395",
    period: 1,
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 68,
        awayScore: 75
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
period Required Must be a positive integer 1-n identifying the period that is ending.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "periodEnd",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The madeShot method is used to post the details related to a successful shot, or a made basket.

URL

http://api.espnalps.com/{version}/basketball/{league}/madeShot?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the gameId, the playerId of the shooter, the playerId of the assisting player, if there is one, the shotType, the number of points scored, a true/false indicator identifying if the score was the result of a fast break opportunity, a true/false indicator identifying if the score was a result of defensive goaltending or not, the court location where the shot was taken from, and a properly formatted context document.

Example Document

{ 
    gameId: "5ffa23ce03648afad2812865",    
    shooter: "4eea69ce03648afad2835396",
    assistedBy: "4eea69ce03648afad2835395",
    shotType: "dunk",
    pointsScored: 2,
    fastBreakOpportunity: true,
    goaltending: false,
    location: [323, 12],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 53,
        awayScore: 55 
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
shooter Required The player id, representing the player who made the shot.
assistedBy Optional The player id representing the player who assisted in making the shot. Not all made shots are assisted. This is an optional field.
shotType Required A text string representing the type of shot that was taken. Must be one of "jump-shot", "layup", "dunk", "tip-in", or "free-throw".
pointsScored Required An integer that represents how many points were scored as a result of the made shot. Must be either 1, 2 or 3.
fastBreakOpportunity Required A true/false indicator to represent whether or not the made shot was attempted during a fast break.
goaltending Required A true/false indicator to represent whether or not the made shot was scored because of a defensive goaltend.
location Required The court location where the made shot was taken.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "madeShot",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The missedShot method is used to post the details surrounding a missed shot or opportunity to score, including free throws.

URL

http://api.espnalps.com/{version}/basketball/{league}/missedShot?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the gameId, the playerId of the shooter, the playerId of the opposing team player who blocked the shot if applicable, the shotType, the number of points that would have been earned if the shot was made, a true/false indicator if the shot was a result of a fast break opportunity, the court location where the shot was attempted from, and a properly formatted context document.

Example Document

{ 
    gameId: "5ffa23ce03648afad2812865",    
    shooter: "4eea69ce03648afad2835396",
    blockedBy: "4eea69ce03648afad2835391",
    shotType: "jump-shot",
    pointsAttempted: 3,
    fastBreakOpportunity: false,
    location: [180, 120],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 63,
        awayScore: 66
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
shooter Required The player id, representing the player who missed the shot.
blockedBy Optional The player id representing the player from the opposing team who blocked the missed the shot. Not all missed shots are blocked.
shotType Required A text string representing the type of shot that was taken. Must be one of "jump-shot", "layup", "dunk", "tip-in", or "free-throw".
pointsAttempted Required An integer that represents how many points would have been scored if the shot was made and not missed. Must be either 1, 2 or 3.
fastBreakOpportunity Required A true/false indicator to represent whether or not the missed shot was attempted during a fast break.
location Required The court location where the missed shot was taken.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "missedShot",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The jumpBall method is used to post the players involved and the winner of the jump-ball event that occurs at the start of a game or OT period. The jumpBall method is also used to post the players involved in a tie-up situation and the team or player who is awarded the ball.

URL

http://api.espnalps.com/{version}/basketball/{league}/jumpBall?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the gameId, the home and away playerId(s) participating in the jump-ball, the winning playerId involved in the jump-ball, the court location of the jumpball, and a properly formatted context document.

Example Document

{ 
    gameId: "5ffa23ce03648afad2812865",
    homePlayer: "4eea69ce03648afad2835365",
    awayPlayer: "4eea69ce03648afad283536b",
    winner: "4eea69ce03648afad2835365",
    location: [150, 200],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 0,
        awayScore: 0
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
homePlayer Required Unique player id from the on field home team roster, representing the home team player involved in the jump-ball/tie-up.
awayPlayer Required Unique player id from the on field away team roster, representing the away team player involved in the jump-ball/tie-up.
winner Required The unique player id representing the home or away team player who won the jump-ball by securing the ball for his team, or whose team was awarded the ball by the possession arrow. Must be either the homePlayer or awayPlayer, identified above, as participating in the jump-ball/tie-up.
location Required The court location where the jumpball occurred.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "jumpBall",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The rebound method is used to submit information indicating who came away with the rebound after a missed shot.

URL

http://api.espnalps.com/{version}/basketball/{league}/rebound?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the gameId, the playerId of the player getting the rebound, the reboundType, the court location where the rebound occurred, and a properly formatted context document.


Example Document

{ 
    gameId: "5ffa23ce03648afad2812865",    
    rebounder: "4eea69ce03648afad2835396",
    reboundType: "defensive",
    location: [12, 180],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 12,
        awayScore: 21
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
rebounder Optional The player id, representing the player who rebounded the missed the shot. Not all rebounds are made by a player, so this field is optional.
reboundType Required A text string representing the type of rebound. Must be one of "offensive", "defensive", "dead-ball", "team-offensive", or "team-defensive". Although rebounder is not a required field, reboundType of "dead-ball" requires a rebounder
location Required The court location where the rebound was secured.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "rebound",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The substitution method is used to record a substitution, a bench player relieving an on field player.

URL

http://api.espnalps.com/{version}/basketball/{league}/substitution?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the playerId of the on court player designated as leaving the court (subbing out), and the playerId for the player from the bench, entering the court, and a properly formatted context document.

Example Document

{ 
    gameId: "5ffa23ce03648afad2812865",    
    exitingPlayer: "4eea69ce03648afad2835365",
    enteringPlayer: "4eea69ce03648afad283537a",
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 12,
        awayScore: 9
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
exitingPlayer Required Unique identifier from the on court roster, representing the player leaving the court on a substitution.
enteringPlayer Required Unique identifier of a player from the team roster, representing the player entering the court on a substitution.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

 {
    time: " 2011-09-10T12:47:21.231+0000",
    request: "substitution",
    result: "okay",  
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The turnover method is used to record a change in possession.

URL

http://api.espnalps.com/{version}/basketball/{league}/turnover?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the gameId, the unique playerId of the player who committed the turnover, the playerId of the player on the opposing team who forced the turnover, the turnover type, the court location where the turnover occurred and a properly formatted context document

Example Document

{ 
    gameId: "5ffa23ce03648afad2812865",    
    committedBy: "4eea69ce03648afad2835396",
    forcedBy: "4eea69ce03648afad283538e",
    turnoverType: "lost-ball",
    location: [111, 26],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 45,
        awayScore: 62
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
committedBy Required The player id, representing the player, or team, who committed the turnover.
forcedBy Optional The player id, representing the player who forced the turnover. Not all turnovers are forced.
turnoverType Required A text string representing the type of turnover that was committed. Must be either "traveling", "lost-ball", "offensive-foul", "out-of-bounds", "violation", "offensive-goaltending" or "thrown-away".
location Required The court location where the turnover occurred.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "turnover",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The timeout method is used to indicate a timeout taken during the course of a game.

URL

http://api.espnalps.com/{version}/basketball/{league}/timeout?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the gameId, the teamId of the team taking the timeout, whether the timeout was a result of a team, official, or media request, and a properly formatted context document.

Example Document

{ 
    gameId: "5ffa23ce03648afad2812865",    
    timeoutTeam: "4eea69ce03648afad2835396",
    timeoutType: "team",
    context: {
        time: "2011-09-10T12:08:21.231-0500",
        homeScore: 19,
        awayScore: 26
    }
}

Field Definitions

Field Name Reequired/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
timeoutTeam Optional The team id, representing the team who called the timeout. Not all timeouts are team timeouts.
timeoutType Required A text string representing the type of timeout. Must be one of "team", "official" or "media".
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

 {
    time: " 2011-09-10T12:47:21.231+0000",
    request: "timeout",
    result: "okay",  
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The foul method posts information related to a foul incurred by either team as a result of a player, team member or fan action. In the course of a game, fouls are usually followed by free throws which should utilize either the madeShot or missedShot method.

URL

http://api.espnalps.com/{version}/basketball/{league}/foul?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

Payload

A JSON document containing the gameId, the playerId of the player who committed the foul, the playerId of the member of the opposing team who drew the foul, if applicable, the foulType, a true/false indicator identifying if the player who committed the foul was ejected from the game, the court location where the foul occurred and a properly formatted context document.


Example Document

{ 
    gameId: "5ffa23ce03648afad2812865",    
    committedBy: "4eea69ce03648afad2835396",
    drewBy: "4eea69ce03648afad283538e",
    foulType: "blocking",
    ejected: false,
    location: [111, 26],
    context: {
        time: "2011-09-10T12:47:21.231-0500",
        homeScore: 45,
        awayScore: 62
    }
}

Field Definitions

Field Name Required/Optional Field Description
gameId Required A unique identifier for the game the user is currently scoring.
committedBy Required The player id, representing the player or team, who committed the foul.
drewBy Optional The player id, representing the player who drew the foul. Not all fouls are drawn.
foulType Required A text string representing the type of foul that was committed. Must be either "blocking", "charging" "shooting", "offensive", "personal", "technical", "flagrant".
ejected Required A true/false indicator to represent whether the player who committed the foul was ejected from the game or not.
location Required The court location where the foul occurred.
context Required A valid context document.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

{
    time: "2011-09-10T12:48:21.231+0000",
    request: "foul",
    result: "okay",
    response: { eventId: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.eventId The unique event identifier of successfully submitted event.

Comments


Description

The deleteEvent method can be used to delete a scoring event from the database. In order to allow an app user to correct for erroneously entered data, the incorrect eventId should be deleted and a new event, of the appropriate type, inserted.

URL

http://api.espnalps.com/{version}/basketball/{league}/deleteEvent/[event id]?token=[your token value]&signature=[your signature value]&key=[your key]

The values in green are used for authentication and must be present with each request as a query string. You need to get values from the login method.

The value in red is the event id of the event you wish to delete.

Response

If everything worked correctly, you'll get a response like the one below. If there was an error, you'll get an error response.

Example

 {
    time: " 2011-09-10T12:47:21.231+0000",
    request: "deleteEvent",
    result: "okay",  
    response: { deletedEvent: "4eea69ce03648afad2835366" }
}

Field Definitions

Field Name Field Description
time A timestamp reflecting when the system received the request.
request A string showing the name of the method you called.
result The string "okay".
response A JSON object containing the response content.
response.deletedEvent The unique event identifier of the deleted event.

Comments