Warehouse - REST API Documentation - American Football

Introduction

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

Header Parameters
x-api-key string

API Key. Your API key identifies you to the system, and specifies your access and quota. This parameter is required on all API calls. See Authentication for more information.

Common Parameters

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

Used to only return a portion of the response. See Partial Response for more information.
ak string

DEPRECATED API Key. Your API key identifies you to the system, and specifies your access and quota. This parameter was required on all API calls, but right now is outdated and is suported for backwards compatibility. If posible, we recomend to send x-api-key as header parameter. See Authentication for more information.
limit integer

Limit the number of records returned by the method. Default is 10, the maximum is 500. See Paging for more information.
offset integer

Ignore the first number of records in the result. See Paging for more information.
responseOk enum

The request should always return a HTTP status code of 200, regardless of any errors.

0
Return appropriate response code (Default)
1
Always return 200
format enum

The format to return the data in.

json
JSON (Default)
xml
XML

Authentication

Each API call must include the header parameter x-api-key

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

It is still possible to specify your API key via the ak query string parameter, however this is not a safe way to exchange the key and is DEPRECATED. If you set both the header and query string parameter, the header parameter will be taken in preference.

Character Set

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

All responses will be provided as UTF-8 strings.

Response Format

All responses to API calls will return in the following format

response      
  meta    
    version The version of the API in use
    code The HTTP status code of the response. Options are:
  • 200 Ok
  • 400 Bad Request. The information you passed into the call was missing or incorrect.
  • 401 Unauthorised. The API key used does not have permission to perform the action you have requested.
  • 404 Not Found. The function cannot be found.
  • 500 Internal Server Error. There was an error on the server.
    status The status of the response. Options are:
  • success
  • failure

If the bulk parameter is used in the call then the status of the call will be a success even if all the individual data elements generate errors.

    request The request path/query string for which this is the response
    time Unix timestamp for the response
    count For a successful request, how many records are being returned
    limit For this request, what was the record limit being applied
  data    
    Successful Requests
      For successful requests this node will contain the information that is specified to be returned in the documentation for the individual call.
    Unsuccessful Requests
    error The type of error. Options:
  • KEY_INVALID The API key is not valid
  • NOTFOUND You have requested an invalid action
  • NOTAUTHORISED You do not have permission to perform that action on the data you have requested
  • DATA_INVALID Some or all of the data you provided with the API call is missing/invalid
  • ERROR An error that doesn't fit into the above categories, you should check the description for more information.
    description A more detailed description of the error, if available.

Partial Response

For ease of consumption or for better performance, you can ask the server to return only a subset of the fields that would normally be returned.

To request a partial response, the fields parameter is used.

The value of the fields parameter is a comma-separated list of fields.

Example

Normal Request

/v1/basketball/leagues/1

Request for Partial Response

/v1/basketball/leagues/1?fields=leagueId,name

Data Validity

Caching strategy should be used, however there may be circumstances where data is removed or changed. Because of this you should be refreshing data at appropriate intervals

Paging

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

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

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

Example

Returns records 1 - 10

/v1/basketball/leagues/1?limit=10

Returns records 11 - 20

/v1/basketball/leagues/1?limit=10&offset=10

External Ids

Numerous entities have a field called externalId. This externalId field is the primary key or unique identifier of this object in the third party system which created this entity.

The externalId of a record MUST be unique for that league.

A number of API calls (not all) support the parameter useExternalForLeague. If this parameter is set to the leagueId of the league for which this externalId applies, then the following fields will be converted to their externalId counterparts.

  • competitionId
  • teamId
  • clubId
  • personId
  • matchId
  • divisionId
  • conferenceId
  • venueId
  • locationId
  • competitorId
  • poolNumber
  • representativeClubId
  • playerTeamId
  • playerClubId
  • broadcastId
  • standingAdjustmentId

The above fields are converted in both query strings and body data.

Note: All fields listed above are converted. You cannot mix normal ids with externalIds in the same call.

Example

If teamId 45 of league 34 has an externalId of TEAM1234 then the following two calls are equivalent.

/v1/basketball/teams/45

/v1/basketball/teams/TEAM1234?useExternalForLeague=34

Entities

Leagues
A league is an organisation that runs a number of competitions.

Competitions
A competition is a grouping of matches. It may have preseason, regular season (Home & Away) and finals matches. A league may have 1 to many competitions.

Clubs
A club is an organisation that has a number of teams

Teams
A group of people form a team and participate in a match within a competition. A team can participate in many competitions. A team can be in 1 league. A team can have 1 club.

Divisions
Divisions

Conferences
Conferences

Competition Conferences
A competition can be played between many conferences

Venues
A venue is a physical location that can host a match

Locations
A location is a group of venues

Persons
A person can participate in a match as either a player, official or staff.

Uploads
An upload is a file/image that is associated with a particular entity. There are a number of different upload types available. Different entities support different types of uploads. The table below indicates which upload types are valid for which entity and to which field the entityId field relates.
entityType uploadType entityId
league logo leagueId
club logo clubId
club jersey clubId
competition logo competitionId
team logo teamId
team photo teamId
person photo personId
uniform photo uniformId

Image Format

The system will only accept image uploads of the following types:

  • image/png
  • image/jpeg

It is strongly recommended to upload PNG files with an alpha channel. This ensures the most flexible usage of the images.

File Size

The file being uploaded must be under 512Kb in size.

Image Dimensions

The image file being uploaded should be square in size and not larger than 1024x1024. If the image is not square then it will be automatically padded with tranparent (or white depending on image format) pixels to achieve a square image.

The system will automatically generate images at defined sizes:

  • T1 - 75x75
  • S1 - 200x200
  • M1 - 400x400
  • L1 - 600x600

If the initial image is smaller than one of the defined sizes, then that size will not be generated. eg. An initial image of 400x400 will not generate an image of 600x600.

Roles
A role is a job performed by a person. A person may have many roles, or have performed them over a time period.

Tournaments
Tournaments
Match Related

Pools
Pools are a grouping of matches within a competition

Rounds
A round is an optional grouping of many matches.

Matches
A match is the actual sporting event between a number of competitors (for team sports generally 2 teams) that occurs at a particular date and time.

Broadcasts
The broadcast section has a list of when and where a particular match is broadcast. A match can be broadcast a number of different ways at a number of different times.

Match Competitors
A competitor (for team sports generally 2 teams) compete in a match at a particular date and time.

Match Players
A list of person (Player) records linked to a match

Match Staff
Staff are people that are assigned to a match, such as Referees, Umpires and Coaches.

Standings
A standing/ladder/table is the ranking of a particular competitor amongst all the other competitors in a competition.

Standings Build
Rebuilds the Standings for a competition

Standings Configurations
A standings configuration is the set of rules that allows a standings to be built.
It can be assigned to a competition via Competitions.

Standings Adjustments
A standings adjustment is the a field by field adjustment to be applied to the standings for a competitor in a competition.

Competition Competitors
List of competitors in a competition

Competition Formats
Each competition can have a series of rules/configation about how its matches are run. Each competition can have one (optional) competition format record.

Competition Player Defaults
Players in a competition can have default values used for bios etc

Drive Summaries
Drive summaries contain information of what had happenned during a specific drive
Statistics

Match Actions
Actions are the individual play by play actions within a match

Team Match Statistics
For each match a team will have a series of statistics. For each match a team will have a set of statistics for each period. A team will also have a set of statistics for period 0, which is the total of the statistics for each period.

Team Round Statistics
For each competition a team will have a series of round statistics. For each competition a team will have a set of round statistics for each period. A team will also have a set of statistics for period 0, which is the total of the statistics for each period.

Team Competition Statistics
For each competition a team will have a series of statistics. For each competition a team will have a set of statistics for each period. A team will also have a set of statistics for period 0, which is the total of the statistics for each period.

Team Conference Statistics
For each Conference within a Competition a Team will have a series of Statistics. A Team will have a set of Statistics for each Period. A Team will also have a set of Statistics for period 0, which is the total of the Statistics for each period.

Person Match Statistics
For each match a person will have a series of statistics. For each match a person will have a set of statistics for each period. A person will also have a set of statistics for period 0, which is the total of the statistics for each period.

Person Round Statistics
For each competition a person will have a series of statistics aggregated from each match in which they have been linked in a given round. A person will have a set of statistics for each period. A person will also have a set of statistics for period 0, which is the total of the statistics for each period in a round.

Person Competition Statistics
For each competition a person will have a series of statistics aggregated from each match in which they have been linked. A person will have a set of statistics for each period. A person will also have a set of statistics for period 0, which is the total of the statistics for each period.

Person Conference Statistics
For each conference within a competition a person will have a series of statistics aggregated from each match in which they have been linked. A person will have a set of statistics for each period. A person will also have a set of statistics for period 0, which is the total of the statistics for each period.

Person Base Career Statistics
Ideally base Career Statistics are not used and all career statistics are built automatically from the Person's Match Statistics. But if all the data for the person is not present then these statistics can be added for a baseline that match statistics can be added to.

Person Career Statistics
Get the detail about a specific person's performance in their career

Configuration Hints
Whilst consuming data from the API you are free to read any statistic column you please. This API call gives the league running the competition the ability to suggest to you what columns they suggest you should be using. This may be because they are not capturing some statistical data.

Match Statistics Build
Rebuilds the statistics for a match

Match Statistics Rebuild from Actions
Rebuilds the match statistics based upon the available match actions. This call would be used if there is a change made to a match action and the statistics for the match need to be rebuilt.

Competition Statistics Rebuild
Statistics Rebuild for a competition

Scoring Locations
Provides a summary for a competion of all the scoring actions, their locations, types and results.

Match Logs
Returns a list of matches (plus statistics) a person has participated in.

Head to Head
Returns a list of matches where the two specified teams have competed against each other.

Statistical Leaders
Provides information about leading players for specific statistics.

Leaders Qualifications
This functionality allows you to set qualifications on certain statistics for a person to be considered a leader. For example to be the leading scorer in the competition you must have played in at least 50% of the team's games. Or to be the most accurate scorer, you must have had more than 5 attempts. The qualifications are set for each statistic for each competition. You can have different criteria for different competitions.

Qualifications for a particular statistic (statisticCode) are performed by comparing another statistic (checkStatisticCode) against a fixed value (value). It is possible to use virtual 'average' statistics in checkStatisticCode(etc: sThreePointersAttemptedAverage). This comparison operation is set by the comparison value. The statisticCode and checkStatisticCode can be the same if you are checking the statistic against itself.

Uniforms
A uniform is worn by members of a team. A team may have a number of different uniform articles (jersey, shorts) as well as different uniforms depending on where they play.

Injuries
A person can have many injuries per team, competition, club. An injury has details such as dates, injury type and return status.

Unregistered Persons
Handle the list of people who participated in the match, yet were unknown to the system.

Reassign Match Records
Reassign a person's Match Records from one person to another

Merge Team Records
Merge a Team and their records from one team to another

Entity Linkages
Link an entity (person/club) to another entity in a different league. This allows aggregation of statitics across leagues.

Livestream - Available Matches
This call is only available to those apikeys that have permission to consume the 'read' streaming API. It lists the matches available to be 'read'.
Definitions

Action Types

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

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

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

Sport Action Types
type subType qualifiers
game      
  start    
  end
  • confirmed
  
period      
  start    
  end
  • confirmed
  
cointoss (empty) Applies to all subTypes:
  • looserchoice
    • kickoff
    • receive
    • endzone
  • nullified
  • winnerchoice
    • kickoff
    • receive
    • endzone
    • winnerteam
  •  
overtime Applies to overtime subType:
  • defense
  • offense
secondhalf
startofgame Applies to startofgame subType:
  • defer
drive Applies to all subTypes:
  • drivetime
  • nullified
  • redzone
  • redzonedown
  • redzonefieldgoalmissed
  • redzonefumblelost
  • redzonegameend
  • redzonehalfend
  • redzoneinterception
  • redzonelostbydowns
  • status
    • started
    • ended
  • timeofpossession
  •  
  • drivetime: Drive time
  • timeofpossession: Time of possession
endofplay (empty) Applies to all subTypes:
  • nullified
  •  
extrapoint (empty) Applies to all subTypes:
  • nullified
  • pointsafterturnover
  • redzone
  •  
blocked Applies to blocked subType:
  • blockedby
nullifiedbypenalty
fieldgoal (empty) Applies to all subTypes:
  • firstandgoal
  • nullified
  • pointsafterturnover
  • redzone
  • yards
  •  
  • yards: Exact field goal yards
blocked Applies to blocked subType:
  • blockedby
nullifiedbypenalty
teamblocked
fumble (empty) Applies to all subTypes:
  • forcedby
  • nullified
  •  
lost Applies to lost subType:
  • recoveredafterlossby
recovered Applies to recovered subType:
  • recoveredby
team Applies to team subType:
  • loss
kickoff (empty) Applies to all subTypes:
  • grossyards
  • kickoffonside
  • kickoffonsideattempt
  • netyards
  • nullified
  •  
  • grossyards: Gross kickoff yards (actual kickoff distance)
  • netyards: Net Kickoff Yards (with Fair Catch and Touchback yards pre-applied)
faircatch
muffed
outofbounds Applies to outofbounds subType:
  • 5yardandrekick
  • 5yardfromoutofbounds
  • takeatthespot
return Applies to return subType:
  • muffed
touchback
outofbounds (empty) Applies to all subTypes:
  • nullified
  •  
kickoff Applies to kickoff subType:
  • penalty
  • penaltyyards
pass (empty) Applies to all subTypes:
  • left
  • middle
  • nullified
  • passbreakupby
  • pat
  • patconverted
  • quarterbackhurriedby
  • quarterbackhurriedbysecondary
  • redzone
  • right
  • target
  • touchdown
  • yards
  •  
  • passbreakupby: Player who broke up pass
  • quarterbackhurriedby: Player who hurried QB
  • quarterbackhurriedbysecondary: Second Player who hurried QB
  • yards: Pass yards
completed
incompleted Applies to incompleted subType:
  • dropped
intercepted Applies to intercepted subType:
  • interceptedby
sacked Applies to sacked subType:
  • fumble
  • rushingyards
spike
penalty (empty) Applies to all subTypes:
  • enforcementspot
    • succeeding
    • previous
    • spotofthefoul
    • deadball
  • nullified
  • reason
    • offside
    • delayofgame
    • illegalforwardpass
    • passinterference
    • holding
    • encroachment
    • falsestart
    • ineligibledownfieldonpass
    • illegalformation
    • illegalmotion
    • illegalsubstitution
    • illegalshift
    • illegalsnap
    • runningintoholder
    • runningintothekicker
    • returnfromoutofbounds
    • intentionalgrounding
    • illegalbat
    • illegalblockinback
    • blockbelowwaist
    • chopblock
    • clipping
    • fighting
    • facemask
    • illegalblockafterfcsignal
    • illegalwedge
    • tripping
    • unnecessaryroughness
    • unsportsmanlikeconduct
    • illegaluseofhands
    • personalfoul
    • horsecollartackle
    • disconcertingsignals
    • blockingoutofbounds
    • equipmentviolation
    • hurdling
    • illegalcontactwithsnapper
    • illegaltouchofkick
    • illegaltouchpass
    • leaping
    • leverage
    • roughingholder
    • roughingthepasser
    • roughingthekicker
    • targeting
    • kickcatchinterference
  •  
  • reason: Penalty reason
accepted Applies to accepted subType:
  • penaltyyards
declined
  • yardLine
offset
play Applies to all subTypes:
  • conversion
    • 0
    • 1
  • conversionattempt
    • 0
    • 1
  • down
    • first
    • second
    • third
    • fourth
  • firstdown
    • rushing
    • passing
    • penalty
    • rushingandpenalty
    • passingandpenalty
  • lateralplay
  • nullified
  • opponenttimeofpossession
  • redzonedown
  • scored
  • status
    • started
    • ended
  • timeofpossession
  • togo
  • type
    • snap
    • kickoff
    • pat
  • yardLine
  •  
  • opponenttimeofpossession: Time of possession for opponent team in case of first kickoff in game
  • timeofpossession: Time of possession for team in case of kickoff
  • togo: how many yards to the first down
  • yardLine: line of scrimmage
punt (empty) Applies to all subTypes:
  • grossyards
  • insidetwenty
  • netyards
  • nullified
  •  
  • grossyards: Gross punt yards (actual kickoff distance)
  • netyards: Net punt yards (with Fair Catch and Touchback yards pre-applied)
blocked Applies to blocked subType:
  • blockedby
downed
faircatch
muffed
outofbounds
return
teamblocked
touchback
reception (empty) Applies to all subTypes:
  • afterlateral
  • afterrecovery
  • nullified
  • reception
  • receptionyards
  • yardsaftercatch
  •  
  • receptionyards: Reception distance in yards
  • yardsaftercatch: Yards gained after pass was caught
recovery
fumble Applies to fumble subType:
  • lostby
return Applies to all subTypes:
  • afterlateral
  • afterrecovery
  • attempt
  • nullified
  • pat
  • yards
  •  
  • yards: Return yards
fieldgoal
fumble
interception
kickoff
punt
teamkickoff
teampunt
rush (empty) Applies to all subTypes:
  • afterlateral
  • afterrecovery
  • attempt
  • left
  • middle
  • nullified
  • pat
  • right
  • yardsgained
  • yardslost
  •  
  • yardsgained: Yards gained by rushing
  • yardslost: Yards lost by rushing
quarterbackkneel
quarterbackscramble
sack (empty) Applies to all subTypes:
  • nullified
  • quarterback
  • sackyards
  •  
  • quarterback: player number of opposing team's quarterback who will get negative rushing yards
  • sackyards: Yards lost due to sack
assisted Applies to assisted subType:
  • assistedby
  • assistedsackyards
unassisted Applies to unassisted subType:
  • fumble
timeout (empty)
other
team
safety (empty) Applies to all subTypes:
  • nullified
  • pointsafterturnover
  •  
nullifiedbypenalty
onepoint Applies to onepoint subType:
  • defensive
teamtwopoint
twopoint
snap (empty) Applies to all subTypes:
  • ballsnapped
  • huddle
  • miscfumble
  • nohuddle
  • nullified
  •  
fieldgoal
punt
shotgun
undercenter
tackle (empty) Applies to all subTypes:
  • assistedby
  • forcedfumble
  • fumble
  • interception
  • kickoff
  • kickoffreturn
  • nullified
  • pass
  • punt
  • puntreturn
  • rush
  • tackleforlossyards
  •  
  • assistedby: Tackle assisted by player
  • tackleforlossyards: Tackle for loss distance in yards
assisted
assistedtackleforloss Applies to assistedtackleforloss subType:
  • assistedtackleforlossyards
unassisted
unassistedtackleforloss
touchdown (empty) Applies to all subTypes:
  • firstandgoal
  • fumblereturn
  • interception
  • kickreturn
  • nullified
  • pointsafterturnover
  • puntreturn
  • reception
  • redzonereception
  • redzonerush
  • rush
  •  
nullifiedbypenalty
twopointconversion (empty) Applies to all subTypes:
  • nullified
  • pointsafterturnover
  • reception
  • redzone
  • rushing
  •  
defensiveconversion Applies to defensiveconversion subType:
  • fumbleconversion
  • interceptionconversion
  • kickconversion
nullifiedbypenalty
participated (empty) Applies to all subTypes:
  • players
  • players: comma-separated list of player numbers

Administrative Action Types
type subType qualifiers  
status     Indicates a change in the status of the match
  delayed
  • prevgame
  • teamlate
  • early
 The start time of the match has been changed. The delay in minutes should be passed in the value field. Negative delays are allowed (to indicate early start).
  loaded   The match has been loaded in the software
  ready   The match is ready to proceed in the software and the teams have been loaded
  inprogress   The match is currently in progress
  periodbreak   The match is currently in progress, but in a break between periods
  interrupted
  • equipment
  • venue
  • weather
  • spectator
  • medical
 The match has been stopped temporarily and will resume after a delay. The delay in minutes should be passed in the value field. The qualifiers can be used to give a reason for the delay.
  cancelled   The match will not be started
  abandoned   The match has been stopped and will not restart
  rescheduled   The match has been stopped (or has not started) and will not start/restart. It will be played again at another time.
  finished   The match has come to the end
  protested   The match has come to the end, but the result has been protested
  complete   The match is complete, all scores have been confirmed and result is official
periodstatus     Indicates a change in the period status
  pending   Indicates the period is about to start
  started   Indicates the period has started
  ended   Indicates the period has ended
  confirmed   Indicates that scores have been confirmed for the period
capturestatus      
  unreliable   Indicates that the state of the game being sent by the software differs significantly from the actual situation.
  reliable   Indicates that the state of the game being sent by the software now matches the actual situation.
clock      
  start    
  stop    
  adjustment   The number of seconds adjustment should be passed in the value field. Negative values are allowed
risk (empty)
  • goal
  • cardyellow
  • var
  • cardred
  • penalty