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
- First download the dependencies, the .zip file.
- Then unzip it somewhere reasonable.
- Then go to eclipse and right click on your project in the Package Explorer
- Select “Build Path” > “Configure Build Path” > “Add External Jars…”
- Navigate to the directory where you unzipped the dependencies, then
google-http-java-client/libs/ and select:
- google-http-client-
.jar - google-http-client-jackson
.jar - jackson-core-
.jar
- google-http-client-
- Click “open”
- Hit “okay”
- Dance
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_id s. |
|
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. |