MCSR Ranked Rest API Document

All endpoints have a ratelimit of 500 requests per 10 minutes unless otherwise specified.
If you want to use API Key with expanded ratelimit, please make a #ticket in our Discord Server

Endpoints

https://api.mcsrranked.com/
https://mcsrranked.com/api/
You can use both, but we would recommend to use first one.

200   Success Response

JSON response when an API request is successfully processed.

Response Type

{
    status: string,
    data: object
}

Sample Response

{
    "status": "success",
    "data": {}
}

400   Data Not Found

JSON response when there's no data. However, as an exception, array type returns an empty array instead of this error.

Response Type

{
    status: string,
    data: null
}

Sample Response

{
    "status": "error",
    "data": null
}

401   Wrong Parameters

JSON response when used wrong parameters. The data of the API response will explain what went wrong.

Response Type

{
    status: string,
    data: string
}

Sample Response

{
    "status": "error",
    "data": "invalid `type` query. it must be >= 0 or <= 3"
}

429   Too Many Requests

JSON response when an API request exceeds the ratelimit.

Response Type

{
    status: string,
    data: string
}

Sample Response

{
    "status": "error",
    "data": "Too many requests"
}

Class   UserProfile

Parameter Type Description
uuid String User's UUID
nickname String User's nickname
roleType Integer User's role type
eloRate Integer? User's Elo rate, If user haven't finished placement matches it will be null
eloRank Integer? User's Elo rank
country String? User's country code. It's lowercased ISO 3166-1 alpha-2 format

Class   Achievement

Parameter Type Description
id String Achievement Identifier
date Date Amount of changed elo rates
data String[] Additional data array
level Integer Level of achievement

Class   MatchInfo

Advanced parameters are only available with /matches/{match_id} endpoint.
Parameter Type Description
id String
type MatchType
season Integer
category String Match completions category. Default is ANY
date Date
players UserProfile[]
spectators UserProfile[]
seed.id String? Seed id if it's ranked filtered seed. it's not real seed number of the seed. it will be null if seed is not filtered.
seed.overworld String? Overworld structure type of the seed. it will be null if seed is not filtered.
seed.bastion String? Bastion remnants type of the seed. it will be null if seed is not filtered.
seed.endTowers Integer[] The zero related tower heights of in The End dimension. it will be empty array if seed is not filtered.
seed.variations String[] Noticable variations of the seed. it will be empty array if seed is not filtered.
result.uuid String? Winner's UUID, It will be `null` If match has draw
result.time Time
forfeited Boolean Whether match has no completions
decayed Boolean Whether match has decayed match
rank.season Integer? Record rank of match's season
rank.allTime Integer? Record rank of all-time
changes[].uuid String UUID of player
changes[].change Integer? Amount of changed Elo rate, if match has placements it will be null
changes[].eloRate Integer? Elo rate of player, if match has placements it will be null
tag String? Special tag of this match. It's used by get matches with tag
completions[].uuid String (Advanced) Player uuid of completion
replayExist Boolean (Advanced) Whether match replay is exist in the server
completions[].time Time (Advanced) Match time of completion
timelines[].uuid String (Advanced) Player uuid of timeline
timelines[].time Time (Advanced) Match time of timeline
timelines[].type String (Advanced) Identifier of timeline

String   UserIdentifier

Identifier used when getting user information. You must use one of the formats below.

Type Description Example
UUID UUID of User, you can also use with dashes(-). bbc886da1b024739b4b80f1542e9f61d
Nickname Nickname of User. It's not case sensitive. RED_LIME
Discord ID Linked Discord ID(Snowflake) of User. Must be discord.[ID] format. discord.338669823167037440

Integer   MatchType

Value Description
1 Casual Match
2 Ranked Match
3 Private Room Match
4 Event Mode Match

Integer   Date

Displays a specific date as an epoch time (timestamp) in seconds. (NOT milliseconds!)

Integer   Time

Displays a specific duration in milliseconds.

Get User Data

Returns the {identifier}'s entire profile data.

GET   https://mcsrranked.com/api/users/{identifier}

ParameterTypeRequired?Description
{identifier}UserIdentifiertrueCheck the `Objects#UserIdentifier` section.
seasonIntegerfalseSpecific season match for statistics (default: current season number)

Response Type

ParameterTypeDescription
uuidStringUUID (without Dashes)
nicknameString
roleTypeInteger
eloRateInteger?Elo rate of current season, If user haven't finished placement matches it will be null
eloRankInteger?rank of current season
countryString?country code with lowercased ISO 3166-1 alpha-2 format
achievements.displayAchievement[]A list of achievements to be displayed ingame
achievements.totalAchievement[]A list of user's every achievements except `achievements.display`
timestamp.firstOnlineDateDate of user's first connection
timestamp.lastOnlineDateDate of user's last connection
timestamp.lastRankedDateDate of user's last ranked match
statistics.season.[key].[ranked | casual]Integer?season statistic for specific match type (ranked or casual)
statistics.total.[key].[ranked | casual]Integer?all-time statistic for specific match type (ranked or casual)
connections.[key].idConnection?Identifier of user's third party connections like Twitch, Discord and etc
connections.[key].nameConnection?Display name of user's third party connections like Twitch, Discord and etc
seasonResultObject?User's Elo data of season
seasonResult.last.eloRateIntegerLast Elo rate of season
seasonResult.last.eloRankInteger?Last Elo rank of season
seasonResult.last.phasePointIntegerLast phase points of season
seasonResult.highestIntegerHighest Elo rate of season
seasonResult.lowestIntegerLowest Elo rate of season
seasonResult.phases[].phaseIntegerPhase number
seasonResult.phases[].eloRateIntegerElo rate at phase ended
seasonResult.phases[].eloRankIntegerElo rank at phase ended
seasonResult.phases[].pointIntegerPhase reword point
weeklyRacesObject[]User's results of all weekly races
weeklyRaces[].idIntegerID of the weekly race
weeklyRaces[].timeTimeFinal time of the weekly race
weeklyRaces[].rankIntegerRank in the weekly race

Show Sample Response

{
    "status": "success",
    "data": {
        "uuid": "7665f76f431b41c6b321bea16aff913b",
        "nickname": "lowk3y_",
        "roleType": 0,
        "eloRate": 1966,
        "eloRank": 4,
        "achievements": {
            "display": [
                {
                    "id": "playoffsResult",
                    "date": 1696807856,
                    "data": [
                        "2"
                    ],
                    "level": 1
                },
                {
                    "id": "seasonResult",
                    "date": 1695081661,
                    "data": [
                        "2",
                        "1"
                    ],
                    "level": 1
                },
                {
                    "id": "bestTime",
                    "date": 1706794941,
                    "data": [],
                    "level": 11
                }
            ],
            "total": [
                {
                    "id": "highestWinStreak",
                    "date": 1706794941,
                    "data": [],
                    "level": 6,
                    "goal": 20
                },
                {
                    "id": "playedMatches",
                    "date": 1706794941,
                    "data": [],
                    "level": 10,
                    "goal": 5000
                },
                {
                    "id": "playtime",
                    "date": 1706794941,
                    "data": [],
                    "level": 8,
                    "goal": 3600000000
                },
                {
                    "id": "wins",
                    "date": 1706794941,
                    "data": [],
                    "level": 9,
                    "goal": 2000
                },
                {
                    "id": "seasonResult",
                    "date": 1704499267,
                    "data": [
                        "3",
                        "3"
                    ],
                    "level": 2
                },
                {
                    "id": "seasonResult",
                    "date": 1686787247,
                    "data": [
                        "1",
                        "8"
                    ],
                    "level": 3
                }
            ]
        },
        "timestamp": {
            "firstOnline": 1676490707,
            "lastOnline": 1707732310,
            "lastRanked": 1707739886
        },
        "statistics": {
            "season": {
                "bestTime": {
                    "ranked": 495485,
                    "casual": 503736
                },
                "highestWinStreak": {
                    "ranked": 12,
                    "casual": 2
                },
                "currentWinStreak": {
                    "ranked": 0,
                    "casual": 1
                },
                "playedMatches": {
                    "ranked": 198,
                    "casual": 11
                },
                "playtime": {
                    "ranked": 128755994,
                    "casual": 6621089
                },
                "forfeits": {
                    "ranked": 1,
                    "casual": 0
                },
                "completions": {
                    "ranked": 112,
                    "casual": 2
                },
                "wins": {
                    "ranked": 135,
                    "casual": 4
                },
                "loses": {
                    "ranked": 53,
                    "casual": 4
                }
            },
            "total": {
                "bestTime": {
                    "ranked": 380341,
                    "casual": 489962
                },
                "highestWinStreak": {
                    "ranked": 18,
                    "casual": 3
                },
                "currentWinStreak": {
                    "ranked": 0,
                    "casual": 1
                },
                "playedMatches": {
                    "ranked": 2864,
                    "casual": 46
                },
                "playtime": {
                    "ranked": 1933913181,
                    "casual": 14962658
                },
                "forfeits": {
                    "ranked": 171,
                    "casual": 13
                },
                "completions": {
                    "ranked": 1345,
                    "casual": 8
                },
                "wins": {
                    "ranked": 1809,
                    "casual": 17
                },
                "loses": {
                    "ranked": 959,
                    "casual": 19
                }
            }
        },
        "connections": {
            "discord": {
                "id": "1037457184952434819",
                "name": "lowkey#0996"
            },
            "youtube": {
                "id": "UC_HX7WdiAWRZgcG7aOYtCNg",
                "name": "lowkey"
            },
            "twitch": {
                "id": "0lowkey",
                "name": "0lowkey"
            }
        },
        "seasonResult": {
            "last": {
                "eloRate": 1966,
                "eloRank": 4,
                "phasePoint": 50
            },
            "highest": 2126,
            "lowest": 1941,
            "phases": [
                {
                    "phase": 1,
                    "eloRate": 2126,
                    "eloRank": 1,
                    "point": 50
                }
            ]
        },
        "weeklyRaces": [
            {
                "id": 1,
                "time": 489237,
                "rank": 8
            }
        ]
    }
}

Get User Matches

Returns the {identifier}'s recent matches

GET   https://mcsrranked.com/api/users/{identifier}/matches

ParameterTypeRequired?Description
{identifier}UserIdentifiertrueCheck the `Objects#UserIdentifier` section.
pageIntegerfalsePagination of match list, it must be 0 to 99. (default: 0)
countIntegerfalseNumber of match count each page, it must 1 to 50. (default: 20)
typeMatchType?falseOnly returns match list of the selected match type. (default: null)
seasonIntegerfalseSpecific season match (default: current season number)
excludedecayBooleanfalseWhether exclude decayed matches (default: false)

Response Type

ParameterTypeDescription
Array[]MatchInfo[]

Show Sample Response

{
    "status": "success",
    "data": [
        {
            "id": 534065,
            "type": 2,
            "season": 3,
            "category": "ANY",
            "date": 1695836921,
            "players": [
                {
                    "uuid": "7e697c9f25e74b3c9f7a7c51797987c4",
                    "nickname": "not_tomorrow_yet",
                    "roleType": 0,
                    "eloRate": 1121,
                    "eloRank": 570,
                    "__v": 0
                },
                {
                    "uuid": "bbc886da1b024739b4b80f1542e9f61d",
                    "nickname": "RED_LIME",
                    "roleType": 3,
                    "eloRate": null,
                    "eloRank": null,
                    "__v": 0
                }
            ],
            "spectators": [],
            "result": {
                "uuid": "7e697c9f25e74b3c9f7a7c51797987c4",
                "time": 268613
            },
            "forfeited": false,
            "decayed": false,
            "rank": {
                "season": null,
                "allTime": null
            },
            "changes": [
                {
                    "uuid": "7e697c9f25e74b3c9f7a7c51797987c4",
                    "change": 17,
                    "eloRate": 1234
                },
                {
                    "uuid": "bbc886da1b024739b4b80f1542e9f61d",
                    "change": null,
                    "eloRate": null
                }
            ],
            "seedType": "shipwreck"
        }
    ]
}

Get Versus Stats

Returns the match stats between {identifier1} and {identifier2} for ranked/casual matches. If there's no match between both users, 400 error will returned.

GET   https://mcsrranked.com/api/users/{identifier1}/versus/{identifier2}

ParameterTypeRequired?Description
{identifier1}UserIdentifiertrueCheck the `Objects#UserIdentifier` section.
{identifier2}UserIdentifiertrueCheck the `Objects#UserIdentifier` section.
seasonIntegerfalseSpecific season match (default: current season number)

Response Type

ParameterTypeDescription
playersUserProfile[]
results.[ranked | casual].[key]Integertotal is just matches count, otherwise are win count of specific player (UUID)
changes.[key]IntegerTotal Elo rate changes in a match between both players

Show Sample Response

{
    "status": "success",
    "data": {
        "players": [
            {
                "uuid": "a0c06d33c69941d09b22e0c98c4233fd",
                "nickname": "jamyreaf",
                "roleType": 0,
                "eloRate": 1637,
                "eloRank": 44
            },
            {
                "uuid": "af22aaab9ee74596a3578bd6345d25b5",
                "nickname": "Priffin",
                "roleType": 0,
                "eloRate": 1637,
                "eloRank": 44
            }
        ],
        "results": {
            "ranked": {
                "total": 3,
                "a0c06d33c69941d09b22e0c98c4233fd": 2,
                "af22aaab9ee74596a3578bd6345d25b5": 1
            },
            "casual": {
                "total": 0,
                "a0c06d33c69941d09b22e0c98c4233fd": 0,
                "af22aaab9ee74596a3578bd6345d25b5": 0
            }
        },
        "changes": {
            "a0c06d33c69941d09b22e0c98c4233fd": 33,
            "af22aaab9ee74596a3578bd6345d25b5": -33
        }
    }
}

Get Versus Matches

Returns the recent matches between {identifier1} and {identifier2}.

GET   https://mcsrranked.com/api/users/{identifier1}/versus/{identifier2}/matches

ParameterTypeRequired?Description
{identifier1}UserIdentifiertrueCheck the `Objects#UserIdentifier` section.
{identifier2}UserIdentifiertrueCheck the `Objects#UserIdentifier` section.
pageIntegerfalsePagination of match list, it must be 0 to 99. (default: 0)
countIntegerfalseNumber of match count each page, it must 1 to 50. (default: 10)
typeMatchType?falseOnly returns match list of the selected match type. (default: null)
seasonIntegerfalseSpecific season match (default: current season number)

Response Type

ParameterTypeDescription
Array[]MatchInfo[]

Show Sample Response

{
    "status": "success",
    "data": [
        {
            "id": 581743,
            "type": 2,
            "season": 3,
            "category": "ANY",
            "date": 1698165617,
            "players": [
                {
                    "uuid": "7665f76f431b41c6b321bea16aff913b",
                    "nickname": "lowk3y_",
                    "roleType": 0,
                    "eloRate": 2027,
                    "eloRank": 2
                },
                {
                    "uuid": "af22aaab9ee74596a3578bd6345d25b5",
                    "nickname": "Priffin",
                    "roleType": 0,
                    "eloRate": 1637,
                    "eloRank": 44
                }
            ],
            "spectators": [],
            "result": {
                "uuid": "af22aaab9ee74596a3578bd6345d25b5",
                "time": 643074
            },
            "forfeited": false,
            "decayed": false,
            "rank": {
                "season": 649,
                "allTime": 1904
            },
            "changes": [
                {
                    "uuid": "af22aaab9ee74596a3578bd6345d25b5",
                    "change": 20,
                    "eloRate": 1898
                },
                {
                    "uuid": "7665f76f431b41c6b321bea16aff913b",
                    "change": -20,
                    "eloRate": 1900
                }
            ],
            "seedType": "buried_treasure"
        }
    ]
}

Get User All of Season Results Data

Returns the {identifier}'s entire profile data.

GET   https://mcsrranked.com/api/users/{identifier}/seasons

ParameterTypeRequired?Description
{identifier}UserIdentifiertrueCheck the `Objects#UserIdentifier` section.

Response Type

ParameterTypeDescription
uuidStringUUID (without Dashes)
nicknameString
roleTypeInteger
eloRateInteger?Elo rate of current season, If user haven't finished placement matches it will be null
eloRankInteger?rank of current season
countryString?country code with lowercased ISO 3166-1 alpha-2 format
seasonResults.{season}.last.eloRateIntegerLast Elo rate of season
seasonResults.{season}.last.eloRankInteger?Last Elo rank of season
seasonResults.{season}.last.phasePointIntegerLast phase points of season
seasonResults.{season}.highestIntegerHighest Elo rate of season
seasonResults.{season}.lowestIntegerLowest Elo rate of season
seasonResults.{season}.phases[].phaseIntegerPhase number
seasonResults.{season}.phases[].eloRateIntegerElo rate at phase ended
seasonResults.{season}.phases[].eloRankIntegerElo rank at phase ended
seasonResults.{season}.phases[].pointIntegerPhase reword point

Show Sample Response

{
    "status": "success",
    "data": {
        "uuid": "9a8e24df4c8549d696a6951da84fa5c4",
        "nickname": "Feinberg",
        "roleType": 3,
        "eloRate": 2047,
        "eloRank": 5,
        "country": "us",
        "seasonResults": {
            "6": {
                "last": {
                    "eloRate": 2276,
                    "eloRank": 8,
                    "phasePoint": 125
                },
                "highest": 2291,
                "lowest": 2276,
                "phases": [
                    {
                        "phase": 2,
                        "eloRate": 2089,
                        "eloRank": 6,
                        "point": 30
                    },
                    {
                        "phase": 3,
                        "eloRate": 2248,
                        "eloRank": 4,
                        "point": 50
                    },
                    {
                        "phase": 4,
                        "eloRate": 2276,
                        "eloRank": 8,
                        "point": 45
                    }
                ]
            },
            "7": {
                "last": {
                    "eloRate": 2047,
                    "eloRank": 5,
                    "phasePoint": 20
                },
                "highest": 2110,
                "lowest": 1539,
                "phases": [
                    {
                        "phase": 1,
                        "eloRate": 1871,
                        "eloRank": 9,
                        "point": 20
                    }
                ]
            }
        }
    }
}

Get Recent Matches

Returns the recent matches.

GET   https://mcsrranked.com/api/matches/

ParameterTypeRequired?Description
pageIntegerfalsePagination of match list, it must be 0 to 99. (default: 0)
countIntegerfalseNumber of match count each page, it must 1 to 50. (default: 20)
typeMatchType?falseOnly returns match list of the selected match type. (default: null)
tagStringfalseSpecific tag of match
seasonIntegerfalseSpecific season match (default: current season number)
includedecayany?falseWhether a include decay matches. if you want to use it, just add parameter only like ?includedecay

Response Type

ParameterTypeDescription
Array[]MatchInfo[]

Show Sample Response

{
    "status": "success",
    "data": [
        {
            "id": 519261,
            "type": 2,
            "season": 2,
            "category": "ANY",
            "date": 1695081655,
            "players": [
                {
                    "uuid": "0c302ac113da46deb653c0e7225a8355",
                    "nickname": "Nadoms",
                    "roleType": 0,
                    "eloRate": 1266,
                    "eloRank": 320
                },
                {
                    "uuid": "c569bf473f5d43eba599e56ec51c050c",
                    "nickname": "Burawoy",
                    "roleType": 0,
                    "eloRate": 1166,
                    "eloRank": 495,
                    "__v": 0
                }
            ],
            "spectators": [],
            "result": {
                "uuid": null,
                "time": 0
            },
            "forfeited": false,
            "decayed": false,
            "rank": {
                "season": null,
                "allTime": null
            },
            "changes": [
                {
                    "uuid": "c569bf473f5d43eba599e56ec51c050c",
                    "change": 0,
                    "eloRate": 1229
                },
                {
                    "uuid": "0c302ac113da46deb653c0e7225a8355",
                    "change": 0,
                    "eloRate": 1264
                }
            ],
            "seedType": "buried_treasure"
        }
    ]
}

Get Match Info

Returns the detailed match info.

GET   https://mcsrranked.com/api/matches/{match_id}

ParameterTypeRequired?Description
{match_id}IntegertrueID of match

Response Type

ParameterTypeDescription
ObjectMatchInfo (Advanced)

Show Sample Response

{
    "status": "success",
    "data": {
        "id": 590105,
        "type": 2,
        "season": 3,
        "category": "ANY",
        "date": 1698623666,
        "players": [
            {
                "uuid": "4427794ee7ad48bc9b53c156fa4092e1",
                "nickname": "kW1st",
                "roleType": 1,
                "eloRate": 1834,
                "eloRank": 12
            },
            {
                "uuid": "b903905bc08f4366a551e957ca4dcd78",
                "nickname": "inlifeiminlove",
                "roleType": 0,
                "eloRate": 1830,
                "eloRank": 13
            }
        ],
        "spectators": [],
        "result": {
            "uuid": "4427794ee7ad48bc9b53c156fa4092e1",
            "time": 809939
        },
        "forfeited": false,
        "decayed": false,
        "rank": {
            "season": 4507,
            "allTime": null
        },
        "changes": [
            {
                "uuid": "4427794ee7ad48bc9b53c156fa4092e1",
                "change": 16,
                "eloRate": 1849
            },
            {
                "uuid": "b903905bc08f4366a551e957ca4dcd78",
                "change": -16,
                "eloRate": 1750
            }
        ],
        "completions": [
            {
                "uuid": "4427794ee7ad48bc9b53c156fa4092e1",
                "time": 809939
            }
        ],
        "timelines": [
            {
                "uuid": "b903905bc08f4366a551e957ca4dcd78",
                "time": 8297,
                "type": "story.form_obsidian"
            },
            {
                "uuid": "b903905bc08f4366a551e957ca4dcd78",
                "time": 8297,
                "type": "story.obtain_armor"
            },
            {
                "uuid": "b903905bc08f4366a551e957ca4dcd78",
                "time": 8269,
                "type": "story.iron_tools"
            }
        ],
        "seedType": "village"
    }
}

Get Elo Leaderboard

Returns Top 150 Leaderboard for Elo rates (it's not always 150 players due to same ranks)

GET   https://mcsrranked.com/api/leaderboard

ParameterTypeRequired?Description
seasonIntegerfalseSpecific season (default: current season number)
countryStringfalseSpecific country code with lowercased ISO 3166-1 alpha-2 format

Response Type

ParameterTypeDescription
season.endsAtDate?Date of season ends. If target season is not current season it will be null
season.numberInteger
usersUserProfile[]
users[].seasonResult.eloRateIntegerFinal Elo rate of player in target season
users[].seasonResult.eloRankIntegerFinal Elo rank of player in target season
users[].seasonResult.phasePointIntegerFinal phase points of player in target season

Show Sample Response

{
    "status": "success",
    "data": {
        "season": {
            "endsAt": 1712448000,
            "number": 4
        },
        "users": [
            {
                "uuid": "3c8757790ab0400b8b9e3936e0dd535b",
                "nickname": "doogile",
                "roleType": 3,
                "eloRate": 2175,
                "eloRank": 1,
                "seasonResult": {
                    "eloRate": 2175,
                    "eloRank": 1,
                    "phasePoint": 40
                }
            },
            {
                "uuid": "17e787d1d6374f818b294f2319db370d",
                "nickname": "silverrruns",
                "roleType": 0,
                "eloRate": 2002,
                "eloRank": 2,
                "seasonResult": {
                    "eloRate": 2002,
                    "eloRank": 2,
                    "phasePoint": 25
                }
            },
            {
                "uuid": "70eb9286e3e24153a8b37c8f884f1292",
                "nickname": "7rowl",
                "roleType": 0,
                "eloRate": 1969,
                "eloRank": 3,
                "seasonResult": {
                    "eloRate": 1969,
                    "eloRank": 3,
                    "phasePoint": 35
                }
            },
            {
                "uuid": "7665f76f431b41c6b321bea16aff913b",
                "nickname": "lowk3y_",
                "roleType": 0,
                "eloRate": 1966,
                "eloRank": 4,
                "seasonResult": {
                    "eloRate": 1966,
                    "eloRank": 4,
                    "phasePoint": 50
                }
            },
            {
                "uuid": "af22aaab9ee74596a3578bd6345d25b5",
                "nickname": "Priffin",
                "roleType": 0,
                "eloRate": 1955,
                "eloRank": 5,
                "seasonResult": {
                    "eloRate": 1955,
                    "eloRank": 5,
                    "phasePoint": 25
                }
            },
            {
                "uuid": "a29a2e3d1ed649f8b122de8ddad2668a",
                "nickname": "Jud0zwerg",
                "roleType": 0,
                "eloRate": 1446,
                "eloRank": 147,
                "seasonResult": {
                    "eloRate": 1446,
                    "eloRank": 147,
                    "phasePoint": 0
                }
            },
            {
                "uuid": "0388b80ebe6c4216b4a8305c0cd27894",
                "nickname": "tommorerow",
                "roleType": 1,
                "eloRate": 1445,
                "eloRank": 148,
                "seasonResult": {
                    "eloRate": 1445,
                    "eloRank": 148,
                    "phasePoint": 5
                }
            },
            {
                "uuid": "8021b1eb133346c3b0b88d19c5be9188",
                "nickname": "gabboooz",
                "roleType": 0,
                "eloRate": 1443,
                "eloRank": 149,
                "seasonResult": {
                    "eloRate": 1443,
                    "eloRank": 149,
                    "phasePoint": 0
                }
            },
            {
                "uuid": "aa0aee82f7a94591a076331d899f836c",
                "nickname": "sacanagem_online",
                "roleType": 0,
                "eloRate": 1439,
                "eloRank": 150,
                "seasonResult": {
                    "eloRate": 1439,
                    "eloRank": 150,
                    "phasePoint": 5
                }
            },
            {
                "uuid": "c7802cb7c30c47aabc1a7ec790ff2260",
                "nickname": "iKme_",
                "roleType": 0,
                "eloRate": 1439,
                "eloRank": 150,
                "seasonResult": {
                    "eloRate": 1439,
                    "eloRank": 150,
                    "phasePoint": 0
                }
            }
        ]
    }
}

Get Season Phase Points Leaderboard

Returns Top 100 Phase Points Leaderboard for Current Season

GET   https://mcsrranked.com/api/phase-leaderboard

ParameterTypeRequired?Description
seasonIntegerfalseSpecific season (default: current season number)
countryStringfalseSpecific country code with lowercased ISO 3166-1 alpha-2 format

Response Type

ParameterTypeDescription
phase.endsAtDate?Date of season ends. If target season is not current season it will be null
phase.numberInteger?Current phase number of the season. If target season is not current season it will be null
phase.seasonInteger
usersUserProfile[]
users[].seasonResult.eloRateIntegerFinal Elo rate of player in target season
users[].seasonResult.eloRankIntegerFinal Elo rank of player in target season
users[].seasonResult.eloRankIntegerFinal phase points of player in target season

Show Sample Response

{
    "status": "success",
    "data": {
        "phase": {
            "endsAt": 1709769600,
            "number": 2,
            "season": 4
        },
        "users": [
            {
                "uuid": "7665f76f431b41c6b321bea16aff913b",
                "nickname": "lowk3y_",
                "roleType": 0,
                "eloRate": 1966,
                "eloRank": 4,
                "seasonResult": {
                    "eloRate": 1966,
                    "eloRank": 4,
                    "phasePoint": 50
                }
            },
            {
                "uuid": "3c8757790ab0400b8b9e3936e0dd535b",
                "nickname": "doogile",
                "roleType": 3,
                "eloRate": 2175,
                "eloRank": 1,
                "seasonResult": {
                    "eloRate": 2175,
                    "eloRank": 1,
                    "phasePoint": 40
                }
            },
            {
                "uuid": "70eb9286e3e24153a8b37c8f884f1292",
                "nickname": "7rowl",
                "roleType": 0,
                "eloRate": 1969,
                "eloRank": 3,
                "seasonResult": {
                    "eloRate": 1969,
                    "eloRank": 3,
                    "phasePoint": 35
                }
            },
            {
                "uuid": "562a308be86c4ec09438387860e792cc",
                "nickname": "Oxidiot",
                "roleType": 0,
                "eloRate": 1942,
                "eloRank": 8,
                "seasonResult": {
                    "eloRate": 1942,
                    "eloRank": 8,
                    "phasePoint": 30
                }
            },
            {
                "uuid": "17e787d1d6374f818b294f2319db370d",
                "nickname": "silverrruns",
                "roleType": 0,
                "eloRate": 2002,
                "eloRank": 2,
                "seasonResult": {
                    "eloRate": 2002,
                    "eloRank": 2,
                    "phasePoint": 25
                }
            },
            {
                "uuid": "af22aaab9ee74596a3578bd6345d25b5",
                "nickname": "Priffin",
                "roleType": 0,
                "eloRate": 1955,
                "eloRank": 5,
                "seasonResult": {
                    "eloRate": 1955,
                    "eloRank": 5,
                    "phasePoint": 25
                }
            },
            {
                "uuid": "fa61606e8131484c8dee506d1ff9a8dc",
                "nickname": "AutomattPL",
                "roleType": 3,
                "eloRate": 1947,
                "eloRank": 6,
                "seasonResult": {
                    "eloRate": 1947,
                    "eloRank": 6,
                    "phasePoint": 25
                }
            },
            {
                "uuid": "aa0aee82f7a94591a076331d899f836c",
                "nickname": "sacanagem_online",
                "roleType": 0,
                "eloRate": 1439,
                "eloRank": 150,
                "seasonResult": {
                    "eloRate": 1439,
                    "eloRank": 150,
                    "phasePoint": 5
                }
            },
            {
                "uuid": "5a2cb29136eb46529adc03aa4583a2d2",
                "nickname": "GradientGray",
                "roleType": 0,
                "eloRate": 1412,
                "eloRank": 180,
                "seasonResult": {
                    "eloRate": 1412,
                    "eloRank": 180,
                    "phasePoint": 5
                }
            },
            {
                "uuid": "745a819973974fe1bb1608e57fd439b6",
                "nickname": "centuriee",
                "roleType": 0,
                "eloRate": 1412,
                "eloRank": 180,
                "seasonResult": {
                    "eloRate": 1412,
                    "eloRank": 180,
                    "phasePoint": 5
                }
            },
            {
                "uuid": "4c3bc64c9f0a4cd988cad7703d80379e",
                "nickname": "ColeTM",
                "roleType": 0,
                "eloRate": 1392,
                "eloRank": 209,
                "seasonResult": {
                    "eloRate": 1392,
                    "eloRank": 209,
                    "phasePoint": 5
                }
            }
        ]
    }
}

Get Season Best Time Leaderboard

Returns Best Time Leaderboard for Current Season

GET   https://mcsrranked.com/api/record-leaderboard

ParameterTypeRequired?Description
seasonIntegerfalseSpecific season. If it's 0, target season will be current season. If it's not defined, get leaderboard for all seasons. (default: undefined)
distinctany?falseType of best time leaderboard. If you send request with this parameter, it returns only the fastest run per player.

Response Type

ParameterTypeDescription
[].rankInteger
[].seasonInteger
[].dateDate
[].idIntegerMatch ID
[].timeTime
[].userUserProfile

Show Sample Response

{
    "status": "success",
    "data": [
        {
            "rank": 1,
            "season": 1,
            "date": 1685157577,
            "id": 284288,
            "time": 433388,
            "user": {
                "uuid": "08476f5847fc4daeba74a2544fc9d65b",
                "nickname": "Zylenox",
                "roleType": 0,
                "eloRate": 1523,
                "eloRank": 90
            }
        },
        {
            "rank": 2,
            "season": 1,
            "date": 1685696875,
            "id": 300983,
            "time": 457763,
            "user": {
                "uuid": "17e787d1d6374f818b294f2319db370d",
                "nickname": "silverrruns",
                "roleType": 0,
                "eloRate": 1818,
                "eloRank": 15
            }
        }
    ]
}

Get Weekly Race Leaderboard

Returns Weekly Race info and leaderboard

GET   https://mcsrranked.com/api/weekly-race/{id?}

ParameterTypeRequired?Description
{id}IntegerfalseSpecific week number (as id in this endpoint). (default: current weekly race)

Response Type

ParameterTypeDescription
idInteger
seed.overworldString
seed.netherString
seed.theEndString
seed.rngString
endsAtDate
leaderboard[].rankInteger
leaderboard[].playerUser
leaderboard[].timeTime
leaderboard[].replayExistBoolean

Show Sample Response

{
    "status": "success",
    "data": {
        "id": 13,
        "seed": {
            "overworld": "142605421743383832",
            "nether": "142605421743383832",
            "theEnd": "142605421743383832",
            "rng": "142605421743383832"
        },
        "endsAt": 1735516800,
        "leaderboard": [
            {
                "rank": 1,
                "player": {
                    "uuid": "4aed1e5e8f5c44e2bc0666e0c03781af",
                    "nickname": "nEmerald",
                    "roleType": 0,
                    "eloRate": 1512,
                    "eloRank": 92
                },
                "time": 324323,
                "replayExist": true
            },
            {
                "rank": 2,
                "player": {
                    "uuid": "92b63a39b36a445fa94c77ae212dcea3",
                    "nickname": "bing_pigs",
                    "roleType": 0,
                    "eloRate": 1512,
                    "eloRank": 92
                },
                "time": 345664,
                "replayExist": true
            },
            {
                "rank": 3,
                "player": {
                    "uuid": "5cd115f0ec1240659db152406c0984a3",
                    "nickname": "yjako",
                    "roleType": 0,
                    "eloRate": 1512,
                    "eloRank": 92
                },
                "time": 354563,
                "replayExist": false
            }
        ]
    }
}