StarCraft 2 Progaming Statistics and Predictions
To use the Aligulac API you first need an API access key. To generate one, please use the button below. You will have to provide your name (or the name of the organization), and a contact e-mail address.
If the request is successful, you will be provided with a 20-character random string. This string will have to be passed with every API request you make as a parameter named apikey
. In the rest of this document, this parameter will be implied.
The API is for the most part self-documenting. The root URI is /api/v1/
. Requests to this URI will return a JSON object describing the available resources and their root URIs, e.g.
{ "period": { "list_endpoint": "/api/v1/period/", "schema": "/api/v1/period/schema/" }, "player" : { "list_endpoint": "/api/v1/player/", "schema": "/api/v1/player/schema/" } }
NOTE: For making requests in the browser, please append ?format=json
to the URI.
The resources available correspond for the most part to the tables in the database, which are described here. In addition to these, we have API access to predictions as well, described below.
Requests for player objects thus need to go to /api/v1/player/
. For a detailed description of each resource, go to the schema URI. This will return a JSON object with the following fields:
get
and post
).application/json
).true
if the field can be null
, false
otherwise.string
, integer
, float
, datetime
etc.). For related objects of another type, this field will read related
1
(all filters available), or the integer 2
(all filters available, including related objects). With very few exceptions, all kinds of filters are allowed.To obtain all objects of a given resource, just make a request to the base resource URI, e.g. /api/v1/period/
. This will return a JSON object with two fields: meta, giving paging information, and objects, which is a list of objects. By default, this will return a limited number of objects per page (normally 20). To control the page size and offset, give the limit
and offset
arguments, e.g.
/api/v1/period?limit=50&offset=100
will return objects number 100-149. In addition, the meta field gives you the URIs for the next and previous pages, as well as the total count of objects.
You can get all objects at once by giving limit=0
, but this is disallowed on some resources and otherwise not encouraged.
If you know the id of the object you are interested in, you can get it directly. For example, to get Leenock's player information, go to /api/v1/player/1/
, since Leenock's id is 1
.
This will return just the object directly, with no metadata and no surrounding list.
If you want to access more than one object, you can request them as a set to save both us and yourself from extra work. If you are interested in Leenock, Creator and Life (ids 1, 2 and 3), you can make a request to
/api/v1/player/set/1;2;3/
Fields that point to related objects will usually be given by resource URIs in the returned objects. For frequently useful information (e.g. players' current rating), the related object(s) will be given as well, although they are often stripped-down versions without detailed information.
You can apply filters to the base URI. They are applied in the following manner:
/api/v1/resourcename/?fieldname__filtername=value
If filtering on related objects is available, this can be done as follows:
/api/v1/resourcename/?relatedobject__fieldname__filtername=value
In principle, these chains can be arbitrarily long. The available filters correspond to those found in Django. Here is a brief overview:
fieldname=value
) or case-insensitive matching for strings.re
module.NOTE: Filtering by events works differently. See common use cases.
To sort by a field, add the parameter order_by=fieldname
for ascending order, and order_by=-fieldname
for descending order.
Requests for predictions do not correspond to the database, and work a little differently, but corresponds more or less exactly to the way the prediction page works. We currently support five different formats:
predictmatch
)predictdual
),
also called GSL-style groupspredictsebracket
)predictrrgroup
)predictproleague
)The URI for match prediction is then /api/v1/predictmatch/id1,id2/
, where id1
and id2
are the ids for the two players. You also have to supply a bo
parameter denoting the match length, and this has to be a positive odd integer. The following conditions apply.
You can give id 0 to denote a BYE, and there is no restriction on duplicate players (which can be useful for proleague style to simulate ace matches).
Requests will return a JSON object containing various information, which you can look through by querying the schema URI. For the last four formats (excluding the single match), the two most important fields are matches
and meanres
. The former describes the already entered results, and the latter describes the median outcome given the former. Each match has a unique identifier which you can use to prescribe results and update the predictions. E.g. to set match identifier abc
to result in 1–3, pass the arguments abc_1=1
and abc_2=3
with the request.
It may be difficult to predict in advance which matches will have which identifiers. If you're unsure, make an empty request with no preset results. The returned object will then give identifiers for as many matches as it can. As you fill in results, new matches may become available.
Unlike the matches
list, the meanres
always contains predictions to the end of the tournament. For example, with a 16-player single elimination bracket, the meanres
list will always contain the full 15 matches, trying to predict who will be in the final. As you enter results, this may disagree with the prediction, and the players in the final may change. Thus, only the matches
list contains “sure” information.
Current ratings are delivered together with player objects, so this will suffice:
/api/v1/player/?current_rating__isnull=false ¤t_rating__decay__lt=4 &order_by=-current_rating__rating &limit=10
Null values come before non-null values, so we must filter out the null ratings first. The filter on decay
is to only select active players. Alternatively, for a cleaner method, just request for ratings directly.
/api/v1/rating/?period=95 &decay__lt=4 &order_by=-rating &limit=10
Note that in this case you have to query for the period you want. There is an alias for rating
called activerating
which automatically filters away inactive ratings, but otherwise works the same way. So you could use:
/api/v1/activerating/?period=95 &order_by=-rating &limit=10
You could use the eventobj
relation to filter matches by events, but since matches are only assigned to the lowest level event objects, you can't use this to get, say, all WCS matches in 2014. That's because no matches are assigned to event object 23398 (which is WCS 2014), rather they are assigned to subevents.
For event objects, two meta-relations are available called uplink
(which links to higher-level events), and downlink
(which links to lower-level events).
uplink__parent
is the ancestor event.downlink__child
is the descendant event.uplink__distance
and downlink__distance
is the distance between them.So to get all WCS matches in 2014 (matches assigned to subevents of the WCS 2014 event), you can use:
/api/v1/match/?eventobj__uplink__parent=23398
This is also available for event objects, so to get all children and grandchildren of WCS 2014 you can use:
/api/v1/event/?uplink__parent=23398 &distance__range=1,2
For these meta-relations you can use the following filters:
This is accomplished by using the in
filter
on the match
resource. Let's assume the we want the history between
PartinG (id 5) and Maru (id 49).
/api/v1/match/?pla__in=5,49&plb__in=5,49
To facilitate easier searching by name (aliases, etc.) we have a different URL endpoint: /search/json/?q=query
. This is the endpoint used by Aligulac's own autocompletion feature, and so it obeys the same rules (e.g. it will search for teams, events and players, and it will be sensitive to things like country names and races). This feature is strictly speaking not part of the API, and so its use does not require an access key.