API Calls

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

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.

Parameter Name Value Description
fields string Used to only return a portion of the response. See Partial Response
ak 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.
limit integer Limit the number of records returned by the method. Default is 10, the maximum is 500.
offset integer Default is 0. Ignore the first number of records in the result. Default is 0
responseOk integer The request should always return a HTTP status code of 200, regardless of any errors. 1 = Yes, 0 = No. Default is 0
format string The format to return the data in. Options are
  • json (Default)
  • xml

Authentication

Each API call must include the query string parameter ak. 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.

Resource or Collections

Most methods will return either a resource or a collection. A resource is generally some kind of entity, a club, team, person, competition etc.

Resources are defined separately in this document

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?ak=YOUR-API-KEY

Request for Partial Response

/v1/basketball/leagues/1?ak=YOUR-API-KEY&fields=leagueId,name

Calls

Entities

Match Related

Statistics