ALIGULAC

StarCraft 2 Progaming Statistics and Predictions

Language:

API documentation

API access key

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.

API overview

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:

  • allowed_detail_http_methods and allowed_list_http_methods: list of accepted HTTP methods (should always be get and post).
  • default_format: default reply format (should always be application/json).
  • default_limit: default page limit when grabbing many objects at once.
  • fields: A dictionary describing each field of the given resource, with the following information:
    • nullable: true if the field can be null, false otherwise.
    • type: Field type (e.g. string, integer, float, datetime etc.). For related objects of another type, this field will read related
    • default: Default value, if any (usually not).
    • help_text: Additional human-readable information.
    The other fields are not of interest.
  • filtering: A dictionary describing the filters available on each field. For each field, this is either a list of filters, the integer 1 (all filters available), or the integer 2 (all filters available, including related objects). With very few exceptions, all kinds of filters are allowed.
  • ordering: A list of fields that allow sorting. With very few exceptions, this will be all fields.

Getting all objects

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.

Getting a single object by ID

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.

Getting several objects by ID

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/

Related objects

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.

Filtering

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:

  • exact, iexact: Exact lookup (can also be done just as fieldname=value) or case-insensitive matching for strings.
  • contains, icontains: Case sensitive or insensitive string containment.
  • startswith, istartswith, endswith, iendswith: Case sensitive or insensitive string prefix or postfix matching.
  • regex, iregex: Case sensitive or insensitive regular expression matching. The regular expression syntax is defined by Python's re module.
  • in: The given field value must be an element of the provided comma-separated list.
  • gt, gte, lt, lte: Numerical orderings >, ≥, < and ≤.
  • range: The given field value must lie between the given values (separated by a comma). Useful for dates.
  • year, month, day, week_day: Applies to date fields, matches only on the specified integer value. Months and week days are numbered from 1, and the week is assumed to start on Sunday.
  • isnull: Takes a boolean, will only match objects where the given field is or is not null.

NOTE: Filtering by events works differently. See common use cases.

Ordering

To sort by a field, add the parameter order_by=fieldname for ascending order, and order_by=-fieldname for descending order.

Prediction requests

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:

  • Single best-of-N matches (predictmatch)
  • Dual tournaments (predictdual), also called GSL-style groups
  • Single-elimination brackets (predictsebracket)
  • Round-robin groups (predictrrgroup)
  • Proleague-style team matches (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.

  • For single matches, you must provide exactly two players.
  • For dual tournaments, you must provide exactly four players.
  • For single elimination brackets, you must provide a number of players that is a power of two.
  • For proleague matches, you must provide an even number of players, one full team before the other (there does not have to be an odd number of players per team).
  • For single elimination, and only for this format, you can give different match lengths for different rounds, just make a comma-separated list with the first round first and the final last.

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.

Common use cases

Get the current top ten rating list

Current ratings are delivered together with player objects, so this will suffice:

/api/v1/player/?current_rating__isnull=false
               &current_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

Filtering by event

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:

  • Direct lookup
  • gt, gte, lt, lte
  • in
  • range

Get the history between two players

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

Searching by name

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.