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

curl -X GET "https://marvelrivalsapi.com/api/v1/heroes/leaderboard/squirrel girl"
     -H "x-api-key: YOUR_API_KEY"

Node.js

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);
}

Python

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}")

Java

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

200

{
    "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
        },
    ]
}

400

{
  "error": true,
  "message": "Invalid hero name or ID. The provided name or ID does not match any known hero.",
  "status": 400
}

401

{
  "error": true,
  "message": "Invalid or missing API key.",
  "status": 401
}

404

{
  "error": true,
  "message": "Hero not found. No hero data was found for the given name or ID",
  "status": 404
}

500

{
  "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).