BinaryBeast API

From BinaryBeast

Jump to: navigation, search



The BinaryBeast API is available to all registered BinaryBeast users. Authentication is handled by supplying your APIKey or with a simple email / password combination

If you find that anything in this page is innacurate or missing, please let us know at

The default return format is JSON, but you may request XML or even CSV by passing the argument APIReturn=[json,xml,csv]

Where to send the requests

All requests are routed through a single URL:

Get an API Key

We recommend using an APIKey instead of a standard email / password combination (though you can still do that if you wish)

You can get your APIKey by logging into - and visiting Settings top right, or visit the following page:


Registered users now have the option of viewing their recent API Requests in their User Settings

There's a new tab called "API Activity/History" - click on it and you'll get a list of recent requests

You can even drill down into each request and view every detail about it - all arguments you sent, and exactly how the server responded

Naming conventions

BinaryBeast was developed using CamelCase arguments / variables. Naturally therefore, the API also uses that same format

However, you can (and the PHP class does this by default in fact) pass an argument api_use_underscores with a value of 1, and it will convert all incoming / outgoing arguments through the API to allow for using underscore_seperated_values

If api_use_underscores is enabled, for example 'APIKey' would become 'api_key', and TourneyTeamID becomes 'tourney_team_id' - just seperate each word with an underscore

Remember that this works BOTH ways - all arguments sent to the API can use underscores, and all returned value keys will be in the snake_case format

Important note: all arguments accepted are NOT case sensitive - TourneyID works just as well as tourneyid

Standardized responses

All services return an array, and 'Result' is ALWAYS included. The value of 'Result' roughly resemble HTTP result headers. IE 200 = the service executed successfully, 500 = internal error, 403 = un-authorized.

Please note: If using our pre-made PHP class, all returned values are objects

Service requests

When calling upon the API, there is 1 mandatory argument called APIService - which tells BinaryBeast exactly what you want to do

The API requests call upon a repository of services, and are broken down by Package.Group.Service

A common example of a service request is from the Tourney package, the TourneyCreate group, and the Create service, like this: Tourney.TourneyCreate.Create - As you hopefully guessed, this would be used to create a new tournament


There are 2 methods of authentication, and along with them, a few mandatory arguments for all api calls:

When using an API Key, you MUST include the following 2 mandatory arguments:

APIKey: Your API key - See the heading Get an API Key for directions on how to get this value

APIService: The service to call, ie Tourney.TourneyCreate.Create

You may also use a standard Email / Password combination, in which case the following there are 3 mandatory arguments:

APIEmail: Your BinaryBeast login email

APIPassword: Your BinaryBeast password

APIService: The service to call, ie Tourney.TourneyCreate.Create

Pre-made interfaces


We have already made a PHP class that does all of the work for you - you can download it On GitHub

Current revision: 3.0.6 (2013-04-19)

You can view the documentation on

Example usage:

//Get the main API Class
//Make sure you setup the values in lib/BBConfiguration.php!

//Instantiate the main class
$bb = new BinaryBeast();

//Let's create a tournament!
$tournament = $bb->tournament();
$tournament->title = 'Test Touranment!';

//Uh oh! time to troubleshoot
if(!$tournament->save()) {

//Success! let's print out a link to the tour
else echo '<a href="' . $tournament->url . '">Check out my new tournament!</a>';


We recently released a set of simple java classes that can be used to access the API, - you can download it here

Current revision: 1.0 - 2011-8-1 (clear your cache if you need to download a fresh copy)

However, we haven't had a chance to document it's usage yet, so ask us directly or figure it out on your own :), we're working on it though

You can view the limited class documentation here

Example usage:

import org.json.JSONArray;
import org.json.JSONObject;
import com.binarybeast.api.BBRequest;
import com.binarybeast.api.BBRequestHandler;
import com.binarybeast.api.BBResult;
import com.binarybeast.api.BinaryBeastAPI;

public class main

         * @param args

        public static void main(String[] args)
                 * Though we don't actually need to save an instance, we still need to instantiate the class so it can be
                 * accessed from BBRequest later, and so it can remember our APIKey

                new BinaryBeastAPI("e17d31bfcbedd1c39bcb018c5f0d0fbf.4dcb36f5cc0d74.24632846");

                //Simple debugging / testing, as this is a simple cli application
                System.out.println("Thanks for testing, welcome to the BinaryBeast API Version: " + BinaryBeastAPI.API_VERSION);

                 * Simple call - search through our list of games for any that have the word "star" in it

                BBRequest.gameSearch("star").execute(new BBRequestHandler()
                        public void onResponse(BBResult result)
                                 * Success!!!!
                                 * For EVERY SINGLE REQUEST RESPONSE, result will be returned, and will roughly reseumble an http result code
                                 * 200 ALWAYS means that the request was successful
                                 * A few common possibilities:
                                 *              401: You're not logged in
                                 *              403: You don't have permission
                                 *              500: Internal error (hopefully you NEVER see this, contact us immediately if you do)

                                if(result.result == 200)
                                        //Let's loop through the results
                                        JSONArray games = result.optJSONArray("Games");
                                        for(int x = 0; x < games.length(); x++)
                                                JSONObject game = games.optJSONObject(x);
                                                System.out.println(x + ": " + game.optString("Game") + " (GameCode: " + game.optString("GameCode") + ")");
                                else System.err.println("Response Error: " + result.result);


If you would like to help out the API, send us your own API class in another language to We'd love to add it here after looking it over


Should anyone be so kind as to send us their own class / interface to the BinaryBeast API, full credit goes out to him of course, just let us know how credit should be given


Tourney Package

CRUD services for managing tournaments

Game Package

This package can be used to lookup games from our database, and retrieve their GameCodes

Country Package

This package can be used to lookup countries from our database, and retrieve their CountryCodes

APICallback Package

This package is used to create custom event callbacks,

For example, when a tournament is completed, it will notify you by calling the URL you supply and it will pass along a bit of information about the event, as you would expect from a CallBack

Personal tools