> For the complete documentation index, see [llms.txt](https://docs.digitomize.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitomize.com/reference/api-reference/leaderboard.md).

# Leaderboard

You can use the endpoint to perform the following queries:

* [Retrieve the leaderboard](#the-leaderboard)
* [Filter the leaderboard by platform](#filter-by-platform)
* [Filter the leaderboard by username](#filter-by-username)

This endpoint gives you all the details on the leaderboard including,

* total number of users
* top 3 users 
* number of users per page
* current page
* total number of pages
*  leaderboard

## The leaderboard

<mark style="color:blue;">`GET`</mark> `https://www.v2api.digitomize.com/user/leaderboard`&#x20;

This endpoint retrieves the whole leaderboard

{% tabs %}
{% tab title="200: OK Successful data retrieval" %}

{% endtab %}

{% tab title="500: Internal Server Error Server Error" %}

{% endtab %}
{% endtabs %}

An example of the response is:

```json
{
    "total_users": 70,
    "top3": [
        {
            "username": "coderdhanraj",
            "picture": "https://res.cloudinary.com/dsazw0r59/image/upload/ar_1.0,c_fill,g_face/f_auto/r_max/v1701666794/users/bqvYU117aieXrUN8tYS4mky8act1.jpg",
            "name": "Dhanraj Chaurasia",
            "codechef": 2035,
            "leetcode": 2478,
            "codeforces": 1905,
            "digitomize_rating": 1905,
            "platform_rating": null
        },
        ...
    ],
    "users_in_page": 5,
    "total_pages": 14,
    "current_page": 1,
    "leaderboard": [
        {
            "username": "priyanshutrivedi818",
            "picture": "https://lh3.googleusercontent.com/a/ACg8ocKHINLEGHdSrFO_D1TqPMqX3UhLKuYfYKNCN5QCiU-3=s96-c",
            "name": "Priyanshu Trivedi",
            "codechef": 2005,
            "leetcode": 2060,
            "codeforces": 1667,
            "digitomize_rating": 1667,
            "platform_rating": null
        },
        ...
    ]
}
```

## Filter by platform

<mark style="color:blue;">`GET`</mark> `https://www.v2api.digitomize.com/user/leaderboard`&#x20;

This endpoint retrieves the leaderboard sorted based on a specified platform

#### Query Parameters

| Name     | Type   | Description                    |
| -------- | ------ | ------------------------------ |
| platform | String | One of the supported platforms |

{% tabs %}
{% tab title="200: OK Successful data retrieval" %}

{% endtab %}

{% tab title="500: Internal Server Error Server Error" %}

{% endtab %}
{% endtabs %}

The response will only include the leaderboard sorted by ratings based on the platform.&#x20;

{% hint style="info" %}
The available platforms in Digitomize include:&#x20;

* geeksforgeeks
* codechef
* codeforces
* atcoder
* codingninjas
* leetcode
  {% endhint %}

Here is an example of the response:

The leaderboard is filtered by the leetcode platform

```json
{
    "total_users": 56,
    "top3": [
        {
            "username": "Mukul_Rawat",
            "picture": "https://res.cloudinary.com/dsazw0r59/image/upload/ar_1.0,c_fill,g_face/f_auto/r_max/v1702761621/users/rA3v7v5sZ8QmkzI3UNprZlx9e1r1.png",
            "name": "Mukul Rawat",
            "codechef": 2052,
            "leetcode": 2481,
            "codeforces": 1709,
            "digitomize_rating": 1724.2949999999998,
            "platform_rating": 2481
        },
        ...
    ],
    "users_in_page": 5,
    "total_pages": 11,
    "current_page": 1,
    "leaderboard": [
        {
            "username": "rahul1995",
            "picture": "https://lh3.googleusercontent.com/a/ACg8ocJV0_ycmW98qj9MUhSEbMZUtDv1buXrn4qkjN1THVyyu50=s96-c",
            "name": "Rahul JAIN",
            "codechef": 1768,
            "leetcode": 2326,
            "codeforces": 1186,
            "digitomize_rating": 1616.57,
            "platform_rating": 2326
        },
        ...
    ]
}
```

## Filter by username

<mark style="color:blue;">`GET`</mark> `https://www.v2api.digitomize.com/user/leaderboard`&#x20;

This endpoint retrieves an individual user's data on the leaderboard

#### Query Parameters

| Name     | Type   | Description  |
| -------- | ------ | ------------ |
| username | String | The username |

{% tabs %}
{% tab title="200: OK Successful data retrieval" %}

{% endtab %}

{% tab title="500: Internal Server Error Server Error" %}

{% endtab %}
{% endtabs %}

Here is an example where we search for Priyanshu's details in the leaderboard.

```json
{
    "user_position": 4,
    "ratings": {
        "codechef": 2005,
        "leetcode": 2060,
        "codeforces": 1667,
        "digitomize_rating": 1667,
        "platform_rating": null
    }
}
```

Feel free to use this API. If you have any issues, you can raise it in [our Discord channel](https://discord.com/invite/bsbBytBqBc).