MarvelRivalsAPI.com
Swagger DocsDiscord
  • Introduction
    • Documentation Overview
  • Errors
  • Rate Limits
  • Endpoints
    • Achievements
      • All Achievements
      • Achievement
    • Battlepass
    • Heroes
      • All Heroes
      • Hero
      • Hero Stats
      • Hero Leaderboard
      • Costumes
        • All Costumes
        • Costume
    • Items
      • All Items
      • Item
    • Maps
      • All Maps
    • Patch Notes
      • All Balances
        • Balance
      • All Dev Diaries
        • Dev Diray
      • All Patch Notes
        • Patch Note
      • Game Versions
      • Seasons
    • Player Stats
      • Find Player
      • Player
      • Update Player
    • Match Stats
      • Match History v1
      • Match
      • Match History v2
Powered by GitBook
On this page

Was this helpful?

  1. Endpoints
  2. Heroes

Hero Leaderboard

GET https://marvelrivalsapi.com/api/v1/heroes/leaderboard/:query

This endpoint retrieves the leaderboard for a specific hero based on their name or ID, and allows filtering the leaderboard by platform (PC, PS, Xbox). The leaderboard data is fetched from an external API and processed for easy consumption.

Headers

Name
Value

Content-Type

application/json

x-api-key*

YOUR API KEY

Query Parameters

Name
Type
Required
Description

query*

string

✔️

The name or ID of the hero to retrieve.

platform

string

❌

The platform for the leaderboard. Options are pc, ps, xbox. If not provided, defaults to pc.

Example Requests

curl -X GET "https://marvelrivalsapi.com/api/v1/heroes/leaderboard/squirrel girl"
     -H "x-api-key: YOUR_API_KEY"
const axios = require("axios");

try {
    const response = await axios.get("https://marvelrivalsapi.com/api/v1/heroes/leaderboard/squirrel girl", {
        headers: {
            "x-api-key": "YOUR_API_KEY"
        }
    });
    console.log(response.data);
} catch (error) {
    console.error("Error fetching balances:", error.response ? error.response.data : error.message);
}
import requests

url = "https://marvelrivalsapi.com/api/v1/heroes/leaderboard/squirrel girl"
headers = {
    "x-api-key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error {response.status_code}: {response.text}")
import java.net.http.*;
import java.net.URI;
import java.io.IOException;

public class ApiClient {
    public static void main(String[] args) {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://marvelrivalsapi.com/api/v1/heroes/leaderboard/squirrel girl"))
            .header("x-api-key", "YOUR_API_KEY")
            .GET()
            .build();

        try {
            HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
            System.out.println(response.body());
        } catch (IOException | InterruptedException e) {
            e.printStackTrace();
        }
    }
}

Response

{
    "players": [
        {
            "info": {
                "name": "Neko",
                "cur_head_icon_id": "30000001",
                "rank_season": {
                    "rank_game_id": 3,
                    "level": 22,
                    "rank_score": "5478.71",
                    "max_level": 23,
                    "max_rank_score": "5496.73",
                    "update_time": 1743716849,
                    "win_count": 150,
                    "protect_score": 0,
                    "diff_score": "18.92"
                },
                "login_os": "1"
            },
            "player_uid": 754556306,
            "matches": 220,
            "wins": 129,
            "kills": 4755,
            "deaths": 1347,
            "assists": 1460,
            "play_time": "2559.96",
            "total_hero_damage": "5149786.31",
            "total_damage_taken": "1909348.10",
            "total_hero_heal": "0.00",
            "mvps": 37,
            "svps": 20
        },
    ]
}
{
  "error": true,
  "message": "Invalid hero name or ID. The provided name or ID does not match any known hero.",
  "status": 400
}
{
  "error": true,
  "message": "Invalid or missing API key.",
  "status": 401
}
{
  "error": true,
  "message": "Hero not found. No hero data was found for the given name or ID",
  "status": 404
}
{
  "error": true,
  "message": "An error occurred while fetching data.",
  "status": 500
}

Response Field Descriptions

Field
Type
Description

players

Array

List of player objects.

players[].info

Object

Basic information about the player.

players[].info.name

String

Player's in-game name.

players[].info.cur_head_icon_id

String

ID of the current avatar or head icon.

players[].info.rank_season

Object

Ranking information for the current season.

players[].info.rank_season.rank_game_id

Number

ID of the ranked game mode.

players[].info.rank_season.level

Number

Current rank level.

players[].info.rank_season.rank_score

String

Current rank score.

players[].info.rank_season.max_level

Number

Highest rank level achieved during the season.

players[].info.rank_season.max_rank_score

String

Highest rank score achieved during the season.

players[].info.rank_season.update_time

Number

Last update timestamp (Unix time).

players[].info.rank_season.win_count

Number

Number of ranked wins.

players[].info.rank_season.protect_score

Number

Score protected due to rank protection mechanics.

players[].info.rank_season.diff_score

String

Score change since the last update.

players[].info.login_os

String

Operating system used at last login (e.g., "1" = Android, "2" = iOS).

players[].player_uid

Number

Unique identifier for the player.

players[].matches

Number

Total matches played.

players[].wins

Number

Total matches won.

players[].kills

Number

Total kills achieved.

players[].deaths

Number

Total number of deaths.

players[].assists

Number

Total number of assists.

players[].play_time

String

Total play time in minutes, as a string with decimal value.

players[].total_hero_damage

String

Total damage dealt to enemy heroes.

players[].total_damage_taken

String

Total damage taken from enemies.

players[].total_hero_heal

String

Total healing done to heroes.

players[].mvps

Number

Number of times the player was MVP (Most Valuable Player).

players[].svps

Number

Number of times the player was SVP (Second Valuable Player).

PreviousHero StatsNextCostumes

Last updated 2 months ago

Was this helpful?