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

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

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

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

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'.

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 Applies to end, abandon subType:
  • confirmed
  • endEarly
 
period      
  start    
  end
  • confirmed
 
comment     Comment text should be passed in the value field
timeout      
  media    
substitution      
  in    
  out    
bulksubstitution Applies to all subTypes:
  • players
  •  
  • players: send qualifiers as string |players:pno1,pno2,pno3|. ex. "players:3,4,5"
in
out
participated Applies to all subTypes:
  • players
  •  
  • players: send qualifiers as string |players:pno1,pno2,pno3|. ex. players:3,4,5;
assist (empty) Applies to all subTypes:
  • powerplay
  • shorthanded
  •  
block (empty)
faceoff (empty)
lost
won
goal (empty) Applies to all subTypes:
  • delayedpenalty
  • emptynet
  • evenstrength
  • extraattacker
  • first
  • gametying
  • gamewinning
  • hattrick
  • overtime
  • penalty
  • powerplay
  • shorthanded
  • suddendeath
  • team1Players
  • team2Players
  • unassisted
  • var
    • review
    • complete
  •  
  • team1Players: send qualifiers as string <br>|team1Players:pno1,pno2,pno3,pno4,pno5|<br>ex. <code>team1Players:2,3,4,5,6</code>
  • team2Players: send qualifiers as string <br>|team2Players:pno21,pno22,pno23,pno24|<br>ex. <code>team2Players:42,43,44,45</code>
disallowed
varoverturned
icing (empty)
keeperchange
fromplayer
toplayer
offside (empty)
penalty (empty) Applies to all subTypes:
  • benchminor
  • boarding
  • buttending
  • changinggoaltenderinterference
  • charging
  • chargingthegoaltender
  • clipping
  • contacttothehead
  • crosschecking
  • delayingthegame
  • directcontacttothehead
  • displacethenet
  • disqualification
  • divingembellishment
  • duration
  • elbowing
  • equipment
  • facemasks
  • faceoffviolation
  • fighting
  • fightingorpunching
  • forfeitofgame
  • goalkeeperhandlingthepuck
  • goaltenderinterference
  • handlingthepuck
  • headbutting
  • highsticking
  • hitafterwhistle
  • hittingfrombehind
  • holding
  • holdingthestick
  • hooking
  • illegalsubstitution
  • indirectcontacttothehead
  • interference
  • kicking
  • kneeing
  • leavingthebench
  • lineuprosterviolation
  • misconduct
  • obstruction
  • prematuresubstitution
  • refusingtoplaythepuck
  • refusingtostarttheplay
  • roughing
  • roughingafterwhistle
  • roughingthegoaltender
  • shotafterwhistle
  • slashing
  • slashingthegoalie
  • slew-footing
  • spearing
  • throwingequipment
  • toomanyplayersontheice
  • tripping
  • unsportsmanlikeconduct
  • var
    • review
    • complete
  •  
  • duration: Duration of penalty
benchdisqualification
benchgamemisconduct
benchmajor
benchminor
benchmisconduct
delayed
disqualification
gamemisconduct
goalie
grossmisconduct
major
match
minor
misconduct
varoverturned
penaltyserve (empty)
penaltyshot
penaltyshotmade
penaltyshotmissed
penaltyshotofftarget
penaltyshotpipe
powerplay (empty)
end
start
powerplayopportunity (empty)
save (empty)
shootout
shootoutsmade
shootoutsmissed
shot (empty)
blocked
offtarget
onpipe
ontarget Applies to ontarget subType:
  • powerplay
  • shorthanded
star (empty)
varreview
complete Applies to complete subType:
  • outcome
    • overturned
    • stands
start Applies to start subType:
  • for
    • goal
    • penalty

Administrative Action Types

type subType qualifiers  
status     Indicates a change in the status of the match
  delayed
  • venue
  • equipment
  • weather
  • officialslate
  • 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
  oncourt   Players on the pitch
  standby   Ready to kick-off
  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
  • venue
  • spectator
  • medical
  • violence
  • icerinkissue
  • glass-breakingissue
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
clock      
  start    
  stop    
  adjustment   The number of seconds adjustment should be passed in the value field. Negative values are allowed
possessionchange      
capturestatus   Applies to all subTypes:
  • score
 
  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.
environmentcondition pitch Applies to pitch subTypes:
  • regular
  • excellent
  • wetfast
  • wetslow
  • frozen
  • bad
  • artificial
 
  weather Applies to weather subTypes:
  • sun
  • clouds
  • rain
  • snow
  • fog
  • roof
  • night
  • normal
 
risk (empty)
  • goal
  • var
  • penalty
 

Playing Surface Definitions

Coordinates

area, x, y and side are defined based upon the diagram below.

x and y are defined as percentage measurments of the total width and height of the ice hockey court. The origin (0,0) is the bottom left corner of the image meaning the top right point is (100,100).

Example:
A North America Ice Hockey court length is 200 feet and goal line is at 11 feet
Therefore the x coordinate of the goal line = 11/200 * 100 = 5.5
and the x coordinate of the other goal line = (200-11)/200 * 100 = 94.5

Action Areas

area is defined by which of the defined boxes the player was in when the action occurred.

The value of area in reference to the diagram are as follows:

Number on diagram Value
1 goalGreen
2 goalRed
3 behindGoal
4 goalBrown
5 leftWing
6 rightWing
7 goalDarkBlue
8 neutralZone

Face-off Spots

The value of spot in reference to the diagram are as follows:

Number on diagram Value
0 spot0
1 spot1
2 spot2
3 spot3
4 spot4
5 spot5
6 spot6
7 spot7
8 spot8

Rink Types(svg)

NCAA Rink(svg)

width 25.9m (85 feet)
length 60.96m (200 feet)
corners radius 6.1m (20 feet)
goal line distance 3.35m (11 feet)
blue line distance 19.51m (64 feet)