Contents

The API enables logged in users to more easily query ladder data.

Currently the API exposes data as it is structured within the database.

The API uses the Django Rest Framework: https://www.django-rest-framework.org/

Usage

You need to be logged in to view the API via the website. If you are, endpoints are listed here: https://aiarena.net/api/
To get an API token go here.

List data objects -

https://aiarena.net/api/ENDPOINT/
Get a list of matches: https://aiarena.net/api/matches/

Get specific item

https://aiarena.net/api/ENDPOINT/ITEM_ID
Get match ID 4567: https://aiarena.net/api/matches/4567

Filter

https://aiarena.net/api/ENDPOINT/?FIELD_NAME=VALUE
Get all active users: https://aiarena.net/api/users/?is_active=true

https://aiarena.net/api/ENDPOINT?search=SEARCH_STRING
Search for users with "lad" in one of their fields: https://aiarena.net/api/users?search=lad

Order

https://aiarena.net/api/ENDPOINT?ordering=FIELD
Get most recent results first: https://aiarena.net/api/results?ordering=-created

Example scenarios:

Download all of a bot's replays:

  1. Obtain the bot's id from https://aiarena.net/api/bots/
  2. Get a list of all the bot's participations in matches: https://aiarena.net/api/match-participations/?bot=BOT_ID_HERE
  3. For each match id in the participants list:
        Get the result for that match: https://aiarena.net/api/results/?match=MATCH_ID_HERE
        Download the replay using the URL in the replay_file field

Use Python to download the bot's latest 100 replays

  1. Obtain your API Token here
  2. Follow the above steps to get the bot's id
  3. Execute the following (after inputting necessary values):
import json
import os

import requests

# Download
bot_id = 0  # insert bot id
token = ''  # insert token you received from admin
file_path = './replays/'  # insert file path
auth = {'Authorization': f'Token {token}'}

# requests.get(url).text returns a dictionary formatted as a string and we need dictionaries
response = requests.get(f'https://aiarena.net/api/match-participations/?bot={bot_id}&ordering=-match', headers=auth)
assert response.status_code == 200, 'Unexpected status_code returned from match-participations'
participation = json.loads(response.text)

# Download the last 5 replays
for i in range(min(5, participation['count'])):
    response = requests.get(f'https://aiarena.net/api/results/?match={participation["results"][i]["match"]}', headers=auth)
    assert response.status_code == 200, 'Unexpected status_code returned from results'

    match_details = json.loads(response.text)
    if match_details['count'] == 0:
        print(f'No result for match {participation["results"][i]["match"]} - skipping')
        continue

    replay_file = match_details['results'][0]['replay_file']
    if replay_file in (None, 'null'):
        print(f'No replay file for match {participation["results"][i]["match"]} - skipping')
        continue

    print(f'Downloading match {participation["results"][i]["match"]} result')
    replay = requests.get(replay_file)  # don't include auth header - AWS doesn't like it
    with open(os.path.join(file_path, str(participation["results"][i]["match"])+'.SC2Replay'), 'wb') as f:
        f.write(replay.content)

Get the top 10 active bots ranked by ELO

Order by elo descending, and limit the page to 10 entries:
https://aiarena.net/api/bots/?active=true&ordering=-elo&limit=10

Update your bot

Below is an example python script for updating your bot.
This includes the ability to update your bot's zip file and data file. 

import requests

my_bot_id = 1                             # You can obtain this from the URL of your bot's page: https://aiarena.net/bots/<bot_id>/
token = "<token here>"                    # insert the token you received from your token page: https://aiarena.net/profile/token/
my_bot_zip_file = "./bot_zip.zip"         # the file path to your bot zip
my_bot_data_zip_file = "./bot_data.zip"   # the file path to your bot's new data zip
my_bot_article_content = """  
    # My bot
    This is my bot. It is very good.
"""                                       # this content appears on your bot's page, under the "Biography" header
my_bot_zip_publicly_downloadable = True   # setting this to False will stop other users downloading your bot zip
my_bot_data_publicly_downloadable = True  # setting this to False will stop other users downloading your bot data


auth = {"Authorization": f"Token {token}"}
with (open(my_bot_zip_file, "rb") as bot_zip, 
      open(my_bot_data_zip_file, "rb") as bot_data):
    response = requests.patch(
        f"https://aiarena.net/api/bots/{my_bot_id}/",
        headers=auth,
        data={
            "bot_zip_publicly_downloadable": my_bot_zip_publicly_downloadable,
            "bot_data_publicly_downloadable": my_bot_data_publicly_downloadable,
            "wiki_article_content": my_bot_article_content
        },
        files={
            "bot_zip": bot_zip,
            "bot_data": bot_data,
        },
    )
    print(response.json())

Request a match between 2 bots

This feature is available to AI Arena supporters.

You can request a match to play between 2 bots of your choosing on the map of your choosing.

Example python script:

import requests

# You can obtain these IDs from the Website API
bot_1_id = 1
bot_2_id = 2
map_id = 3

# insert the token you received from your token page: https://aiarena.net/profile/token/
token = "<token here>"

auth = {"Authorization": f"Token {token}"}
response = requests.post(
    f"https://aiarena.net/api/match-requests/request_single/",
    headers=auth,
    data={
        "bot1": bot_1_id,
        "bot2": bot_2_id,
        "map": map_id
    },
)

"""
Prints:
{'message': 'Match requested successfully', 'match_id': <the new match ID>}
"""
print(response.json())