# 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitomize.com/reference/api-reference/leaderboard.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.