NAV
Java cURL

Introduction

Introduction

Welcome to the Rank API documentation.

We have a Java client library, or you can use direct HTTP requests (with cURL or some other tool). You can view code examples in the dark area to the right, and you can switch between Java and cURL.

This API allows you to manage a leaderboard, adding scores and listing them with powerful filters. You can list your leaderboard filtering by date and tag. You can get the top scores, the scores for a particular user, and the scores nearby another score.

Requests

Any tool that can make HTTP requests can use the API by requesting the correct URI. Requests should be made HTTPS so the traffic is encrypted Alternatively, you can use our Java client library. You can chose the cURL examples or the Java client examples on the right.

Responses

Example response object:

{
  "data": [
    {
      "id": 5,
      "user_id": 1,
      "score": 220,
      "tag": "level two",
      "created_at": "2015-07-12T12:16:22.018"
    }
  ],
  "meta": {
    "total": 55,
    "links": {
      "prev": "https://tmwild.com/api/leaderboards?offset=1&page_size=1",
      "next": "https://tmwild.com/api/leaderboards?offset=35&page_size=1"
    }
  }
}

Each response will be JSON formatted. The object will contain data and meta. Data will contain the data requested, or information about the action performed. Meta is information about the response itself. See the meta section for more info. All example responses in the rest of this document will show the data object and not the full response object.

API Key

curl -H "Authorization: Bearer $TOKEN" "https://tmwild.com/api/leaderboards"

Each request must be made with a valid API Key. You must send a bearer authorization header with your request. The Java client handles this for you.

To get your API key, sign up on the homepage of this website, then sign in to the dashboard. Once in the dashboard, click on the “settings” tab and you will be taken to a page where you can see your API key.

Meta

Example meta object:

{
  "total": 55,
  "links": {
    "prev": "https://tmwild.com/api/leaderboards?offset=5&page_size=5",
    "next": "https://tmwild.com/api/leaderboards?offset=15&page_size=5"
  }
}

Each response will include a meta object, which contains info about the response itself. For requests returning lists the meta object will contain a total key which is set to the total number of objects the request describes. If this number is large, it will be different than the number of objects returned, as the results are paginated. In this case, the meta object will also contain a links object. This object will contain next and/or previous, which are links that point to the next and previous page of responses, respectively. If there are no more results or if it is the first response the next or previous keys will not exist, respectively.

Pagination

With requests that ask for lists in response, there are two url parameters you can pass: page_size, which indicates how many elements should be returned per page, and offset, which indicates which element to start at. The default page_size is 5, and the maximum is 25. The default offset is 1, which refers to the first element.

These parameters will not be shown in the example requests for brevity.

Rate Limit

The number of requests that can be made through the API is currently limited to 3600 per 24 hours per Auth token, refreshing at midnight. If you exceed the rate limit, you will get a 429 error response. For all the errors that can be returned, see the error section below.

Date Format

All of the dates in requests and responses are to be interpretted as UTC. They must be in the ISO 8601 format YYYY-MM-DDTHH:mm:ss for example: "1994-03-06T23:45:11".

Java Client

To use the Java client, the setup includes importing the library and instantiating a client using your API key. We’ll assume these steps have been taken for all of the example code.

import rank.*;
RankClient client = RankClient("myAPIKey");

Further, every function saving or listing will throw an IOException, which can be inspected (ioe.getMessage()) to see what the problem was. They map to the Rank API Error Codes.

The Java Client library uses pagination in a similar way to the raw HTTP API. A ScoreList represents one page of responses (and can be iterated over), and to get other pages, use scoreList.next() and scoreList.previous(). They return null if there are no such pages.

Installation - Eclipse

Leaderboards

Get the top scores

Fetching the data:

Sort sort = Sort.ASCENDING;
String tag = "level one";
Date startDate = null;
Date endDate = null;
ScoreList scores = client.getTopScores(sort, tag, startDate, endDate);

curl "https://tmwild.com/api/leaderboards"
  -X GET
  -H "Authorization: Bearer myAPIKey"

Example Response:

[
  {
    "id": 1,
    "user_id": 10,
    "score": 400,
    "tag": "level_3",
    "created_at": "2015-07-12T12:16:22"
  },
  {
    "id": 2,
    "user_id": 8,
    "score": 120,
    "tag": "level_3",
    "created_at": "2015-07-12T12:16:22"
  }
]

This retrieves the top or bottom scores of your leaderbaord.

Query Parameters

Parameter Required Type Default Description
sort no String "descending" The order the results will be returned, either "ascending" or "descending".
tag no String A leaderboard tag to filter the results with.
start_date no Date String The beginning of time. The start date for a date range filter.
end_date no Date String Now The end date for a date range filter. Must be after start_date.

Get a user’s scores

Fetching the data:

int[] userIds = new int[]{13, 14};
Sort sort = Sort.ASCENDING;
String tag = "level one";
Date startDate = null;
Date endDate = null;
ScoreList scores = client.getUserScores(userIds, sort, tag, startDate, endDate);

curl "https://tmwild.com/api/leaderboards?user_id=1"
  -X GET
  -H "Authorization: Bearer myAPIKey"

Example Response:

[
  {
    "id": 3,
    "user_id": 1,
    "score": 450,
    "tag": "full_armor",
    "created_at": "2015-07-12T12:16:22"
  },
  {
    "id": 2,
    "user_id": 1,
    "score": 430,
    "tag": "bonus_level",
    "created_at": "2015-07-12T12:16:22"
  },
  {
    "id": 1,
    "user_id": 1,
    "score": 400,
    "tag": "full_armor",
    "created_at": "2015-07-12T12:16:22"
  }
]

This retrieves a list of a user’s scores in descending order of time created.

Query Parameters

Parameter Required Type Default Description
user_id yes Integer The ID for the user to query. To query multiple users at once, comma separate user_ids.
sort no String "descending" The order the results will be returned, either "ascending" or "descending".
tag no String A leaderboard tag to filter on.
start_date no Date String The beginning of time. The start date for a date range filter.
end_date no Date String Now The end date for a date range filter. Must be after start_date.

Create a new score

Creating the score:

int userId = 1;
int score = 220;
String tag = "level two";

Score s = new Score(userId, score, tag);
client.saveScore(s);

curl "https://tmwild.com/api/add_score"
  -X POST
  -H "Authorization: Bearer myAPIKey"
  -H "Content-Type: application/json"
  -d '{"user_id":1,"score":220,"tag":"level two"}'

Example Response:

{
  "id": 5,
  "user_id": 1,
  "score": 220,
  "tag": "level two",
  "created_at": "2015-07-12T12:16:22"
}

This endpoint creates a new score in the leaderboard and returns the score object back upon success.

Data Parameters

Parameter Required Type Description
user_id yes Integer The ID of the user to create a leaderboard entry for.
score yes Integer The score for the entry in the leaderboard.
tag no String An identification tag for a leaderboard entry.

Create a new score and list nearby scores

Creating the score:

int userId = 1;
int score = 220;
String tag = "level two";
Score s = new Score(userId, score, tag);
String filterTag = tag;

int radius = 2;
ScoreList scores = client.saveScoreAndList(s, radius, Sort.ASCENDING, filterTag);

curl "https://tmwild.com/api/add_score_and_list"
  -X POST
  -H "Authorization: Bearer myAPIKey"
  -H "Content-Type: application/json"
  -d '{"user_id":1,"score":220,"tag":"level two","radius":1}'

Example Response:

[
  {
    "id": 53,
    "user_id": 8,
    "score": 222,
    "tag": "level two",
    "created_at": "2015-03-12T17:12:22"
  }, {
    "id": 5,
    "user_id": 1,
    "score": 220,
    "tag": "level two",
    "created_at": "2015-03-14T18:26:22"
  }, {
    "id": 28,
    "user_id": 3,
    "score": 219,
    "tag": "level one",
    "created_at": "2015-07-11T17:46:22"
  }
]

Add a new score and receive the scores above and below the new score. The parameters for adding the new score are in the POST data, while the parameters for listing nearby scores are in the URL parameters. The standard pagination does not apply to this endpoint. page_size and offset are ignored, instead relying on the radius and new score entry to dictate which scores are returned.

Data Parameters

Parameter Required Type Description
user_id yes Integer The ID of the user to create a leaderboard entry for.
score yes Integer The score value for the entry in the leaderboard.
tag no String An identification tag for a leaderboard entry.

Query Parameters

Parameter Required Type Default Description
radius yes Integer The number of scores to return above and below the user’s score.
sort no String "descending" The order the results will be returned, either "ascending" or "descending".
filter_tag no String A leaderboard tag to filter on. Must be either empty or the same as tag.

Errors

The Rank API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is malformed
401 Unauthorized – Your API key is wrong
405 Method Not Allowed – You tried to access a leaderboard with an invalid method
406 Not Acceptable – You requested a format that isn’t json
429 Too Many Requests – You’re requesting too many leaderboard scores
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.
Java cURL