Endpoints

/

Get an object containing the URLs for the various parts of the competition interface.

{
    "arenas": "...",
    "teams": "...",
    "corners": "...",
    "config": "...",
    "state": "...",
    "matches": "..."
}

/arenas

Get an object containing all arenas.

{
    "arenas": {
        "...": "..."
    }
}

The arena objects returned are in the same format as those described below. The keys of the arenas mapping are the names of the arenas.

/arenas/ name

Get information about an arena.

{
    "name": "...",
    "display_name": "...",
    "colour": "...",
    "get": "..."
}

If present, the colour key contains the colour of the arena in HTML hash format (eg: #00ff00).

/teams

Get an object containing all teams.

{
    "teams": {
        "...": "..."
    }
}

The team objects returned are in the same format as those described below. The keys of the teams mapping are the TLAs of the teams.

/teams/ tla

Get information about a team.

{
    "name": "...",
    "get": "...",
    "tla": "...",
    "league_pos": "...",
    "location": {
      "get": "...",
      "name": "..."
    },
    "rookie": "...",
    "scores": {
        "game": "...",
        "league": "..."
    }
}

/teams/ tla /image

Get the team image.

/corners

Get an object containing all corners.

{
    "corners": {
        "...": "..."
    }
}

The corner objects returned are in the same format as those described below. The keys of the corners mapping are the numbers of the corners.

/corners/ number

Get information about a corner.

{
    "number": "...",
    "get": "...",
    "colour": "..."
}

/current

Get information about parts of the competition state which change with the current time.

{
    "delay": "...",
    "matches": "...",
    "staging_matches": "...",
    "shepherding_matches": "...",
    "time": "..."
}

The delay value is the amount of delay in seconds currently active. Note that this value is only useful during match periods (it will otherwise be 0).

The matches key is a list of the matches which are currently being played, as measured by the current time falling between the start and end of their slot. They are presented in the same format as the /matches endpoint uses.

The staging_matches key is a list of the matches which are currently being staged, as measured by the current time falling between the open and close values of their staging times. They are presented in the same format as the /matches endpoint uses.

The shepherding_matches key is a list of the matches which are currently being shepherded for, as measured by the current time falling between the earliest shepherding signal value and time when staging closes. They are presented in the same format as the /matches endpoint uses.

The time key is the current time on the server.

/state

Get the latest commit that the competition is working with.

{
    "state": "..."
}

/config

Get general information about the configuration of the competition and the host.

{
    "match_slots": {
        "pre": "...",
        "match": "...",
        "post": "...",
        "total": "..."
    }
}

/locations

Get information about the locations within the venue.

{
    "locations": {
        "..." : "..."
    }
}

The location objects returned are in the same format as those described below. The keys of the locations mapping are the canonical identifier of each location.

/locations/name

Get information about a named location within the venue.

{
    "display_name": "...",
    "get": "...",
    "teams": [ "..." ],
    "shepherds": {
        "name": "...",
        "colour": "..."
    }
}

/matches

Get a load of matches.

You can specify which matches are returned with various queries.

type

The type of match.

arena

The arena the match is in.

num

The number of the match.

game_start_time

The start time of the game.

game_end_time

The end time of the game.

slot_start_time

The start time of the timeslot allocated to the game.

slot_end_time

The end time of the timeslot allocated to the game.

Each parameter can be taken in the form of: <start>..<end>, ..<end>, <start>.. and <value>.

You can also limit the number of matches returned by passing a value to the limit query parameter. This can be both a positive and negative integer. Positive limits start from the first match and work forwards, whilst negative limits start from the last match and work backwards.

{
    "last_scored": "...",
    "matches": [
        {
            "arena": "...",
            "display_name": "Match ...",
            "knockout_bracket": "...",
            "num": "...",
            "scores": {
                "game": {
                    "...": "...",
                    "...": "...",
                    "...": "...",
                    "...": "..."
                },
                "league": {
                    "...": "...",
                    "...": "...",
                    "...": "...",
                    "...": "..."
                },
                "normalised": {
                    "...": "...",
                    "...": "...",
                    "...": "...",
                    "...": "..."
                },
                "ranking": {
                    "...": "...",
                    "...": "...",
                    "...": "...",
                    "...": "..."
                }
            },
            "teams": [
                "...", "...", "...", "..."
            ],
            "times": {
                "game": {
                    "end": "...",
                    "start": "..."
                },
                "slot": {
                    "end": "...",
                    "start": "..."
                },
                "staging": {
                    "opens": "...",
                    "closes": "...",
                    "signal_teams": "...",
                    "signal_shepherds": {
                        "...": "...",
                    }
                }
            },
            "type": "..."
        }
    ]
}

last_scored contains the same value as in the following endpoint. Any dates are in ISO 8601 format.

Only one of the league or normalised sub-keys of scores will be present, though they contain the same data. league will be present for league matches while normalised will be present for knockout matches.

knockout_bracket is present only for knockout matches.

Notably, teams which are disqualified or no-show from a match will have a normalised (league) score of zero but will still have a position value.

The staging deadline is available in times.staging.closes while the times.staging.signal_shepherds value is when shepherds should start looking for teams although this isn’t a strict value.

/matches/last_scored

{
    "last_scored": "..."
}

last_scored contains the highest match number which has a score assigned, but may be null if no scores have yet been entered.

/periods

Get a list of match periods. A match period is a block of time during which a collection of matches (of the same type) occur. For example, the first morning of the first day of the competition might have one period, and the Knockouts might be another.

{
    "periods": [
        {
          "type": "...",
          "description": "A description of the period for humans",
          "end_time": "...",
          "matches": {
            "first_num": "...",
            "last_num": "..."
          },
          "max_end_time": "...",
          "start_time": "..."
        }
    ]
}

The matches field will only be present if there are matches there are matches in this period.

/knockout

Get information about the knockouts. This comprises structural information (currently only a list of “brackets”) and a list of “rounds” of matches.

Brackets are typically used to express the logical structure of the matches in terms of the knockout, but have no bearing on the scheduling of the matches. This for example enables having an “Upper” and “Lower” bracket when running a double-elimination knockout. Brackets have a name and a display_name. The former can be used to cross reference the knockout_bracket value on a match.

Rounds are groups of matches which are scheduled as a block. Matches from different brackets may appear within the same round. Each round is expressed as a list of matches which make up that round. Matches are expressed using the same format as the /matches endpoint.

{
    "rounds": [
        [
            "...",
            "...",
            "...",
            "..."
        ],
        [
            "...",
            "..."
        ],
        [
            "..."
        ]
    ],
    "structure": {
        "brackets": [
            {
                "name": "...",
                "display_name": "..."
            }
        ]
    }
}

/knockout/structure

Get structural information about the knockouts. This is equivalent to the structure key in the /knockout endpoint.

{
    "brackets": "..."
}

/tiebreaker

Get the tiebreaker match, or raise a 404 error if one does not exist. The match is expressed in the same format as the /matches endpoint.

{
    "tiebreaker": "..."
}