Leaderboard API


You can get Leaderboard details for a particular challenge using following API endpoint:

 https://api.hackerearth.com/challenges/v1/leaderboard/

Authentication

The client authentication is done using your unique client_id and client_secret.

You can refer to your profile settings for client_id and client_secret under Leaderboard API section.

client_id

Type: String

Description: client_id is a 67 character random key that serves as an identification for a particular client and must be provided when communicating with the API as a parameter to the API endpoint.

Example: d8a20ae8e475209er4b1faa72ede88a174423cc2029c.api.hackerearth.com

client_secret

Type: String

Description: client_secret is a 40 character random key that serves as an identification for a particular client and must be provided when communicating with the API as a parameter to the API endpoint.

Example: 2b0ff29f4f8751487540604cdab5611e6135f41c


Making requests

client_id, client_secret and challenge_slug are the required parameters for making request to this API endpoint. There is page_index as an optional parameter, you can provide this parameter for pagination.

All the requests to the API must be made using POST request method.

client_id and client_secret are explained above.

challenge_slug

Type: String

Description: challenge_slug is an unique string that you can find in the challenge URL. Remember: challenge_slug is case-sensitive. Please provide an exact challenge_slug as reference to below example.

Example: If the challenge URL is: https://www.hackerearth.com/january-easy-16/ the challenge_slug will be january-easy-16.

page_index [Optional Parameter]

Type: Integer

Description: The page index for leaderboard details.

Sample request using python

#!/usr/bin/env python

import json
import requests

CLIENT_ID = "d8a20ae8e475209e0eb1faa72ede88a174423cc2029c.api.hackerearth.com"
CLIENT_SECRET = "2b0ff29f4f8751487450604cdab5611e6135f41c"
CHALLENGE_SLUG = "january-easy-16"

payload = {
    'client_id': CLIENT_ID,
    'client_secret': CLIENT_SECRET,
    'challenge_slug': CHALLENGE_SLUG,
    'page_index': 3
}
r = requests.post("https://api.hackerearth.com/challenges/v1/leaderboard/", data=json.dumps(payload))
print r.json()

Using cURL

curl --data '{"client_id": "d8a20ae8e475209e0eb1faa72ede88a174423cc2029c.api.hackerearth.com", "client_secret": "2b0ff29f4f8751487450604cdab5611e6135f41c", "challenge_slug": "january-easy-16", "page_index": 3}' https://api.hackerearth.com/challenges/v1/leaderboard/


Response

Response returned will be in JSON format. If you don't provide page_index parameter by default it will return the 1st top 50 developers details else it will return respective page's leaderboard details.

As example we have requested page_index as 3 then the JSON response returned will look like:

Sample response

{
    "problems_count": 6,
    "challenge_url": "https://www.hackerearth.com/january-easy-16/",
    "challenge_slug": "january-easy-16",
    "total_score": 600,
    "challenge_name": "January  Easy '16",
    "page_max_rank": 386,
    "challenge_end_utc": "02-01-2016 19:00:00 UTC",
    "page_min_rank": 101,
    "message": "Request successful",
    "challenge_start_utc": "02-01-2016 16:00:00 UTC",
    "mcode": "SUCCESS",
    "total_developers": 763,
    "page_index": 3,
    "max_page_index": 16,
    "leaderboard": [
        {
            "username": "cheater1",
            "profile": "https://www.hackerearth.com/users/cheater1/",
            "name": "Cheater Developer",
            "problems_solved": 2,
            "score": 200,
            "time_taken": "00:14:12",
            "cheater": true
        },
        {
            "username": "developer1",
            "profile": "https://www.hackerearth.com/users/developer1/",
            "name": "Awesome Developer",
            "problems_solved": 2,
            "rank": ,
            "score": 200,
            "time_taken": "00:22:32"
        },
        {
            ...
        }
    ]
}

mcode

Type : String

Description: Message code abbreviated as mcode.

message

Type: String

Description: A message for user regarding the success of request.

message and mcode are related to each other according to the following table:

mcode message
SUCCESS Request successful.
FAILED Request failed.

ecode

Type: List

Description: Error codes abbreviated as ecode.

emessage

Type: List

Description: A message explaining the error occurred during request processing.

emessage and ecode are related to each other according to the following table:

ecode emessage
AUTHFAILED Authentication Failed.
ARGMISSING Request argument missing.
CHALLENGENOTFOUND Challenge not found.
MUSTBEINT Parameter must be integer.
PAGEINDEXEXCEEDED Max page index exceeded. Max page index is .
LIMITEXCEEDED Client exceeded its request limit. Please contact support@hackerearth.com.
ACCESSERROR You are not authorized to access this feature. Please contact support@hackerearth.com.

If developers get caught cheating in a particular challenge they will be marked as "cheater": true and they won't have any rank. Leaderboard details returned will be sorted by rank.


Errors (Mishandled API responses)

If you have provided wrong client_id or client_secret, the JSON response returned will look like:

{
    "message": "Request failed.",
    "ecode": [
         "AUTHFAILED"
    ],
    "emessage": [
        "Authentication Failed."
    ],
    "mcode": "FAILED"
}

If mandatory POST arguments are not provided, the JSON response returned will look like:

{
    "message": "Request failed.",
    "ecode": [
        "ARGMISSING"
    ],
    "emessage": [
        "Request argument missing: 'challenge_slug'."
    ],
    "mcode": "FAILED"
}

If the type of page_index is not integer, then the JSON response returned will look like:

{
    "message": "Request failed.",
    "ecode": [
        "MUSTBEINT"
    ],
    "emessage": [
        "'page_index' must be integer."
    ],
    "mcode": "FAILED"
}

If page_index exceeds max_page_index, then the JSON response returned will look like:

{
    "message": "Request failed.",
    "ecode": [
        "PAGEINDEXEXCEEDED"
    ],
    "emessage": [
        "Max page index exceeded. Max page index is <max_page_index>."
    ],
    "mcode": "FAILED"
}

If wrong challenge_slug is provided, then the JSON response returned will look like:

{
    "message": "Request failed.",
    "ecode": [
        "CHALLENGENOTFOUND"
    ],
    "emessage": [
        "Challenge not found."
    ],
    "mcode": "FAILED"
}

If user is not authorized to access the test, then the JSON response returned will look like:

{
    "message": "Request failed.",
    "ecode": [
        "ACCESSERROR"
    ],
    "emessage": [
        "You are not authorized to access this feature. Please contact support@hackerearth.com."
    ],
    "mcode": "FAILED"
}

If the API request limit has exceeded, then the JSON response returned will look like:

{
    "message": "Request failed.",
    "ecode": [
        "LIMITEXCEEDED"
    ],
    "emessage": [
        "Client exceeded its request limit. Please contact support@hackerearth.com."
    ],
    "mcode": "FAILED"
}

If any other issue occurred do reach us out at sudip@hackerearth.com

Notifications
View All Notifications