Introduction

The Altius API allows you to read data from tenant databases using a simple REST API.

BETA

This is currently a BETA API. All efforts will be made to not have breaking changes. New endpoints and additional data being added to endpoints will not be considered breaking changes

The BETA period is expected to end on July 31st, 2024

Please review the CHANGE LOG below

Authentication

In order to use the API, you should authenticate your request by including your API Key as a Request Header with key X-API-KEY

Header: X-API-KEY:secret-key

Your API Key can be generated in the Altius Admin System. Please request an API Key from your system administrator.

Headers

Make sure you have the following content type headers are set on every request:

Accept: application/json Content-Type: application/json

All API endpoints with return valid JSON including error messages.

URI

The Altius API is hosted on the following base URI:

https://api.altius.live/v2/

Errors

Error Message Response:


{
    message:  "Unauthorized API Key"
}

Altius uses conventional HTTP response codes to indicate the success or failure of an API request. The table below contains a summary of the typical response codes:

Rate Limiting

For the BETA period The API is rate limited to 1200 requests per miniute per API Key across all end points. All responses include headers describing the current rate limit status:

Certain endpoints are used for real-time streaming, broadcast and scoreboard requirements. These endpoints will be either exempt from Rate Limiting or have a separate limit associated with them. This will be indicated on a per endpoint basis.

Collections

Sample Collection


{
    "data": [
                {   id: 33,
                    name:  'John Smith'
                },
                {
                    id: 34,
                    name: 'Jane Doe'
                },
                ...
             ],
    links:  {...},
    meta:   {...}
}

Endpoints that return a collection will return an array of records in a data top-level key.
Other top-level keys will be added for pagination and metadata as required.

Pagination

Requests for collections return a maximum of 10 results. Subsequent pages of results can be accessed using the page query parameter

GET /v2/competitions?page=3

QUERY PARAMETERS

In addition to the data key, collections will also include meta and links that provide information on the paginated results.

PAGINATION METADATA

Sorting

Requests for collections can be sorted based on one or more fields. The sort query parameter is used to determine by which property the collection will be sorted.

The default sort order along with optional sort properties are documented with each collection endpoint.

One or more properties can be included in the sort query parameter, separated by a comma. Sorting is ascending by default and can be reversed by adding a hyphen (-) to the start of the property name.

EXAMPLES

Records

Sample Record


{
    "data":  {   id:                33,
                 name:              'John Smith',
                 'date_of_birth':   '1980/02/33'
                 ...
             },

}

Endpoints that return a single record will return a json object in the data key.

A list of properties and datatypes for each table are documented in the Tables section.

Including

Sample Record with includes


{
    "data":  {   id:                33,
                 name:              'John Smith',
                 'date_of_birth':   '1980/02/33'
                 'country'      :   {
                                        'name' => 'Canada',
                                        'code'


                 }
                 ...
             },

}

Requests for single records can have modifiers that automatically include related records and collections.

These includes will return with the main record properties in sub keys in the JSON hierarchy.

A description of the includes and relationships for each table are documented in the Tables section.

Endpoints

API Endpoints are listed below. These will be added to as nescessary during the BETA period.

Competition Collection

GET /v2/competitions

Returns a collection of Competitions

SORTING OF COLLECTION

Competition Record

GET /v2/competitions/{id}
Returns a single competition record by ID

PROPERTIES

Competition Summary

GET /v2/competitions/{id}
Returns a single competition record by ID with summary data included

PROPERTIES

Included Relations

Competition All

GET /v2/competitions/{id}/all
Returns a single competition record by ID with complete data included

PROPERTIES

Included Relations

Match Record

GET /v2/Matches/{id}

Returns a single match record by ID

PROPERTIES

Match Timing

GET /v2/matches/{id}/timing

Returns match timing record match record by ID

The timing endpoint is a high performance endpoint providing real-time clock information for a specific match.

Following the BETA period this endpoint will be exempt from standard Rate Limits. It is being designed to be accessed every 500ms per API Key.
Data supplied by this endpoint is subject to change in the BETA period.

The following data properties are available in the match timing endpoint:

Match Summary

GET /v2/matches/{id}/summary
Returns a single Match record by ID with summary data included

PROPERTIES

Included Relations

Match All

GET /v2/matches/{id}/all
Returns a single Match record by ID with full data included

PROPERTIES

Included Relations

Tables

The following property definitions are supplied for all tables acccessible from the API.
Some tables have direct endpoints, while other tables are accessed via includes.

Change Log

Changes to the API are detailed here