Abios API

The Abios API Developer Hub

Welcome to the Abios API developer hub. You'll find comprehensive guides and documentation to help you start working with Abios API as quickly as possible, as well as support if you get stuck. Let's jump right in!

NEW! You can find you personal developer dashboard and request log here.

Tournaments

Tournaments are what holds everything together

In our data Tournaments are the umbrellas that hold and group all Series and Matches together. To do this in a structured way, there are two additional concepts that we use called Stage and Substage, which we'll get into more below. In addition to just grouping, Tournaments also hold a lot of data about the Tournament itself such as where it is played, who will be casting it, prize pools etc. For the full rundown you can look in the API reference.

Stages

Stages are, as of now, only a grouping of Substages. The only data they hold is a name that describes itself in the context of the Tournament.

Substages

Substages, like Stages, also have a name element and groups Series together. Each Substage also have a type that dictates how those Series are played out. The types can be:

Group

This is the most common Substage type and means that the Series are played in a round robin or swiss format. Groups are usually played over a longer period of time and participating competitors earn points based on how well they play.

Single Elimination Bracket

Single elimination (SE) brackets are the simplest type of, what is sometimes refereed to as a, knockout bracket. A SE bracket is at its core a tree structure in which the competitors compete and eliminate (or knockout) half of the participating competitors at each round of the tree. Typically all competitors start out in the first round (say the quarterfinals) and compete to reach, and win, the grand final. However, it is not entirely uncommon that some competitors are seeded to a later stage of the bracket, leaving some of the earlier rounds in the bracket partially unplayed.

A single elimination bracket.

A single elimination bracket.

Double Elimination Bracket

Double elimination (DE) brackets are basically the the same as a SE bracket but with an additional lower or losers bracket. What this means is that, unlike SE brackets where a competitor is eliminated as soon as it loses one Series, a competitor that loses a Series in a DE bracket gets another opportunity to get to the finals through the lower bracket. In effect all competitors must loose two Series to be eliminated from a DE bracket.

A double elimination bracket.

A double elimination bracket.

GSL Bracket

GSL brackets are a special variant of DE brackets used in qualification Substages. As you can hear from the name they originated in the Starcraft scene and are by many considered the most fair qualification method. In practice they are a DE bracket starting at the semifinals where the competitors who would normally reach the grand final, qualify onwards instead.

A GSL bracket.

A GSL bracket.

Bracket Coordinates

For you, as an API user, to be able to draw up fancy looking brackets we have devised a coordinate system that places Series in different locations in a bracket (and also tells you what to call them). Bracket coordinates come in a JSON format, which you read more closely about under BracketPosition in the resources, it looks like this:

{
  "part": "UB",
  "col": 2,
  "offset": 4
}

Using BracketPosition

Depending on if the bracket in question is a double or single elimination bracket (DE or SE) the bracket coordinates will contain different "part" values that corresponding to what part of the bracket the series belongs.

A SE bracket only has an upper bracket (UB) where as a DE bracket will have a upper bracket, a lower bracket (LB) and a grand final (GF). Both SE and DE brackets may or may not have a 3rd place series, or lower finals (LF). See picture below as an example.

The parts of a bracket.

The parts of a bracket.

column
The value of "column" denotes which column in that part of the bracket the series belongs. Column numbers starts at 0 and are incrementally increased from right to left in each part of the bracket. For instance, column 0 in an UB part is the final series and column 2 denotes the quarterfinal column, and so on.

offset
'offset' denotes the offset from the first Series in this part of the bracket, starting with 1 in each part's respective final. Each Series offset is incrementally counted from the top to the bottom in each column of the bracket.

As brackets are symmetrical column and offset relate to each other in a way that makes the brackets easy to draw.

UB BracketPosition

Upper brackets are have a very simple symmetry, where each new column added to the left of the bracket is twice as large as the previous column. As a result the relationship between column and offset is given by the following formula 2^col <= offset < 2^col+1. For example, the quarterfinals of an UB (column 2) have offsets 4-7 (2^2 <= offset < 2^3) starting with the top seeded series (offset = 4) at the top of the column. See this picture as an example:

Columns and offsets in an upper bracket.

Columns and offsets in an upper bracket.

LB BracketPosition

The lower bracket has a different symmetry, where every other column doubles in size making each "column height" appear twice. The result is that the relationship between column and offset is not as straight forward, but can be described by this formula:

##
# For a given column (col) the offset values will be in the range
# of min_off and max_off.
##

# Determine column height
ch = 2**(col//2)
_ch = ch

# Determine offset for this "column pair" in the LB
if col%2 != 0:
	off = ch + 1
else:
	off = 1

# Add the offest of all "column pairs" in the LB
while ch > 1:
	off += ch
	ch = ch/2

min_off = off
max_off = off+_ch-1

print "Offsets for column %d: %d <= offset <= %d" % (col, min_off, max_off)

See this picture as an example:

Columns and offsets in a lower bracket.

Columns and offsets in a lower bracket.


What's Next

Next "level" in the hierarchy are Series and Matches, lets have a look!

Series & Matches

Tournaments

Tournaments are what holds everything together