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

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). 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
  • confirmed
 
period      
  start    
  end
  • confirmed
 
comment     Comment text should be passed in the value field
2pt   Applies to all 2pt subTypes:
  • 2ndchance
  • fastbreak
  • fromturnover
  • pointsinthepaint
  • blocked
 
  (blank)    
  dunk    
  layup    
  fadeaway    
  tipin    
  jumpshot    
  alleyoop    
  drivinglayup    
  hookshot    
  floatingjumpshot    
  stepbackjumpshot    
  pullupjumpshot    
  turnaroundjumpshot    
  wrongbasket    
3pt   Applies to all 3pt subTypes:
  • 2ndchance
  • fastbreak
  • fromturnover
  • blocked
 
  (blank)    
  fadeaway    
  jumpshot    
  floatingjumpshot    
  stepbackjumpshot    
  pullupjumpshot    
  turnaroundjumpshot    
  wrongbasket    
freethrow   Applies to all freethrow subTypes:
  • 2ndchance
  • fastbreak
  • fromturnover
 
  1of1    
  1of2    
  1of3    
  2of2    
  2of3    
  3of3    
jumpball      
  (blank)    
  startperiod    
  unclearposs    
  lodgedball    
  heldball    
  blocktieup    
  outofbounds    
  outofboundsrebound    
  doubleviolation    
  won    
  lost    
assist      
block      
rebound      
  defensive Applies to defensive subType:
  • team
 
  offensive Applies to offensive subType:
  • team
 
  defensivedeadball    
  offensivedeadball    
foul   Applies to all foul subTypes:
  • 1freethrow
  • 2freethrow
  • 3freethrow
  • oneandone
 
  offensive Applies to offensive subType:
  • block
  • charge
  • double
  • flagrant1
  • flagrant2
 
  personal Applies to personal foul subType:
  • shooting
  • looseball
  • double
  • flagrant1
  • flagrant2
 
  technical Applies to technical subType:
  • double
  • classa
  • flagrant2
  • contactdeadball
  • lifting
 
  unsportsmanlike    
  disqualifying    
  benchTechnical Applies to benchTechnical subType:
  • double
  • classa
 
  coachTechnical Applies to coachTechnical subType:
  • double
  • classa
  • direct
 
  adminTechnical Applies to adminTechnical subType:
  • administrative
  • classb
  • benchclassb
  • coachclassb
  • coachindirect
adminTechnical subtype stands for technical fouls that are not included in any statistics.
  coachDisqualifying    
foulon      
timeout      
  full    
  short    
  officials Applies to official subType:
  • bloodrule
  • callreview
 
  media    
  commercial    
steal      
turnover      
  (blank)    
  offensivegoaltending    
  laneviolation    
  ballhandling    
  dribbling    
  badpass    
  lostball    
  overandback    
  backcourt    
  doubledribble    
  outofbounds    
  travel    
  shotclock    
  offensive    
  3sec    
  5sec Applies to 5sec subType:
  • team
 
  8sec    
  10sec    
  24sec    
  lifting    
  other Applies to other subType:
  • team
 
substitution      
  in    
  out    
clock     (At some point in the future the clock messages will be made administrative only)
  start    
  stop    
  adjustment
  • second_plus
  • second_minus
  • minute_plus
  • minute_minus
The number of seconds adjustment should be passed in the value field. Negative values are allowed

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
  • underreview
  • 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
shotclock      
  adjustment
  • kickedball
  • foul
The number of seconds adjustment should be passed in the value field. Negative values are allowed
possessionchange      
possessionarrowchange      
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.

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 basketball court. The origin (0,0) is the bottom left corner of the image meaning the top right point is (100,100).

Example:
A FIBA Standard Basketball Court length is 28m and the 3pt line is at 6.75m
Therefore the x coordinate of the 3pt line = 6.75/28 * 100 = 24.1
and the x coordinate of the other 3pt line = (28-6.75)/28 * 100 = 75.89

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 underbasket
2 inthepaint
3 insiderightwing
4 insideright
5 insidecenter
6 insideleft
7 insideleftwing
8 outsiderightwing
9 outsideright
10 outsidecenter
11 outsideleft
12 outsideleftwing
13 backcourt

Court Types(svg)

FIBA Court(svg)

NCAA Old Court(svg)

NCAA New Court(svg)