Player

GET https://marvelrivalsapi.com/api/v1/player/:query

This endpoint retrieves player data for a specific player identified by uid or username. It processes player statistics and related data, such as match history, rank history, heroes, and maps.

IMPORTANT: Searching player stats by username is a new feature and is not always reliable. Searching player stats by player uid is more stable.

Headers

Name	Value
Content-Type	application/json
x-api-key*	YOUR API KEY

Query Parameters

Name	Type	Required	Description
username*	string	✔️	The username of the player
season	integer	❌	The season number for which the stats are retrieved (defaults to current season).

Example Requests

cURL

curl -X GET "https://marvelrivalsapi.com/api/v1/player/Sypeh"
     -H "x-api-key: YOUR_API_KEY"

Node.js

const axios = require("axios");

try {
    const response = await axios.get("https://marvelrivalsapi.com/api/v1/player/Sypeh", {
        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/player/Sypeh"
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/player/Sypeh"))
            .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

{
  "uid": "player1234",
  "name": "Player One",
  "updates": {
    "additionalProp1": {}
  },
  "player": {
    "player_id": "player1234",
    "nickname": "Player One",
    "isPrivate": false
  },
  "overall_stats": {
    "additionalProp1": {}
  },
  "match_history": [
    {
      "match_id": "match123",
      "date": "2024-02-10T15:30:00Z",
      "result": "win",
      "kills": 5,
      "deaths": 3,
      "assists": 2
    }
  ],
  "rank_history": [
    {
      "season": 2,
      "rank": "Gold",
      "points": 1500
    }
  ],
  "hero_matchups": [
    {
      "hero_id": 101,
      "win_rate": 75.5
    }
  ],
  "team_mates": [
    {
      "teammate_id": "player5678",
      "nickname": "Teammate One"
    }
  ],
  "heroes_ranked": {
    "additionalProp1": 1,
    "additionalProp2": 1,
    "additionalProp3": 1
  },
  "heroes_unranked": {
    "additionalProp1": 2,
    "additionalProp2": 2,
    "additionalProp3": 2
  },
  "maps": {
    "additionalProp1": 10,
    "additionalProp2": 10,
    "additionalProp3": 10
  }
}

400

{
  "error": "Invalid query parameter or missing query"
}

401

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

500

{
  "status": "error",
  "message": "An unexpected error occurred. Please try again later."
}

Response Field Descriptions

Field	Type	Description
uid	Number	Unique identifier for the player (e.g., 1005053199).
name	String	Name of the player (e.g., "FriiZoLoGYy").
updates	Object	Contains various timestamps related to updates for the player.
updates.info_update_time	String	Timestamp of the last information update (e.g., "1/30/2025, 8:10:24 PM").
updates.last_history_update	String	Timestamp of the last history update (e.g., "4/3/2025, 1:24:57 AM").
updates.last_inserted_match	String	Timestamp of the last inserted match (e.g., "4/3/2025, 12:57:27 AM").
updates.last_update_request	String	Timestamp of the last update request (e.g., "4/3/2025, 2:16:38 AM").
player	Object	Contains the player's profile information.
player.uid	Number	Unique identifier for the player (same as the root uid).
player.level	String	Level of the player (e.g., "53").
player.name	String	Name of the player (e.g., "FriiZoLoGYy").
player.icon	Object	Contains information about the player's icon.
player.icon.player_icon_id	String	Unique ID for the player's icon (e.g., 30000031).
player.icon.player_icon	String	URL or path to the player's icon image (e.g., /players/heads/player_head_30000031.png).
player.rank	Object	Contains information about the player's rank.
player.rank.rank	String	Rank of the player (e.g., "Gold III").
player.rank.image	String	URL to the rank image (e.g., /ranked/gold.png).
player.rank.color	String	Color associated with the player's rank (e.g., #FFDA57).
player.team	Object	Contains information about the player's team.
player.team.club_team_id	String	ID for the club team, if applicable (e.g., empty string).
player.team.club_team_mini_name	String	Mini name of the club team, if applicable (e.g., empty string).
player.team.club_team_type	String	Type of the club team (e.g., 0).
player.info	Object	Contains various statistics about the player.
player.info.completed_achievements	String	Number of completed achievements (e.g., 79).
player.info.login_os	String	Operating system used for login (e.g., "Playstation").
player.info.rank_game_season	Object	Contains rank information for multiple game seasons.
player.info.rank_game_season.[game_id]	Object	Contains specific rank data for each game season.
player.info.rank_game_season.[game_id].rank_game_id	Number	ID for the rank game (e.g., 1).
player.info.rank_game_season.[game_id].level	Number	Player's level in the game season (e.g., 6).
player.info.rank_game_season.[game_id].rank_score	Number	Player's rank score in the game season (e.g., 3537.6236).
player.info.rank_game_season.[game_id].max_level	Number	Maximum level for the game season (e.g., 8).
player.info.rank_game_season.[game_id].max_rank_score	Number	Maximum rank score for the game season (e.g., 3722.4733).
player.info.rank_game_season.[game_id].update_time	Number	Timestamp of the last update for the game season rank (e.g., 1736409285).
player.info.rank_game_season.[game_id].win_count	Number	Number of wins in the game season (e.g., 52).
player.info.rank_game_season.[game_id].protect_score	Number	Protect score in the game season (e.g., 3).
player.info.rank_game_season.[game_id].diff_score	Number	Difference in score for the game season (e.g., -16.893).
overall_stats	Object	Contains the player's overall match statistics.
overall_stats.total_matches	Number	Total number of matches played by the player (e.g., 402).
overall_stats.total_wins	Number	Total number of wins by the player (e.g., 213).
overall_stats.unranked	Object	Contains statistics for unranked matches.
overall_stats.unranked.total_matches	Number	Total number of unranked matches played by the player (e.g., 379).
overall_stats.unranked.total_wins	Number	Total number of unranked wins by the player (e.g., 199).
overall_stats.unranked.total_assists	Number	Total number of assists in unranked matches (e.g., 2948).
overall_stats.unranked.total_deaths	Number	Total number of deaths in unranked matches (e.g., 1953).
overall_stats.unranked.total_kills	Number	Total number of kills in unranked matches (e.g., 4562).
overall_stats.unranked.total_time_played	String	Total time spent playing unranked matches (e.g., "53h 30m 8s").
overall_stats.unranked.total_time_played_raw	Number	Raw time played in unranked matches (e.g., 192608.24119138718).
overall_stats.unranked.total_mvp	Number	Total number of MVPs in unranked matches (e.g., 52).
overall_stats.unranked.total_svp	Number	Total number of SVPs in unranked matches (e.g., 53).
overall_stats.ranked	Object	Contains statistics for ranked matches.
overall_stats.ranked.total_matches	Number	Total number of ranked matches played by the player (e.g., 19).
overall_stats.ranked.total_wins	Number	Total number of ranked wins by the player (e.g., 10).
overall_stats.ranked.total_assists	Number	Total number of assists in ranked matches (e.g., 90).
overall_stats.ranked.total_deaths	Number	Total number of deaths in ranked matches (e.g., 108).
overall_stats.ranked.total_kills	Number	Total number of kills in ranked matches (e.g., 372).
overall_stats.ranked.total_time_played	String	Total time spent playing ranked matches (e.g., "3h 17m 58s").
overall_stats.ranked.total_time_played_raw	Number	Raw time played in ranked matches (e.g., 11878.013068199158).
overall_stats.ranked.total_mvp	Number	Total number of MVPs in ranked matches (e.g., 5).
overall_stats.ranked.total_svp	Number	Total number of SVPs in ranked matches (e.g., 4).
rank_history	Array	Contains the player's rank progression history.
rank_history.[i].match_time_stamp	Number	Timestamp of the match (e.g., 1743656176).
rank_history.[i].level_progression	Object	Contains the level progression details.
rank_history.[i].level_progression.from	Number	Previous level (e.g., 8).
rank_history.[i].level_progression.to	Number	New level (e.g., 7).
rank_history.[i].score_progression	Object	Contains the score progression details.
rank_history.[i].score_progression.add_score	Number	Added score (e.g., -15.65039580673556).
rank_history.[i].score_progression.total_score	Number	Total score (e.g., 3665.295436259427).
hero_matchups	Array	Contains matchups with various heroes.
hero_matchups.[i].hero_id	Number	Unique ID for the hero (e.g., 1025).
hero_matchups.[i].hero_name	String	Name of the hero (e.g., "cloak & dagger").
hero_matchups.[i].hero_class	String	Class of the hero (e.g., "Strategist").
hero_matchups.[i].hero_thumbnail	String	URL of the hero's thumbnail (e.g., /heroes/transformations/cloak-dagger-headbig-0.webp).
hero_matchups.[i].matches	Number	Number of matches played against the hero (e.g., 8).
hero_matchups.[i].wins	Number	Number of wins against the hero (e.g., 4).
hero_matchups.[i].win_rate	String	Win rate against the hero (e.g., "50.00").
team_mates	Array	Contains information about the player's teammates.
team_mates.[i].player_info	Object	Information about the teammate.
team_mates.[i].player_info.nick_name	String	Nickname of the teammate (e.g., "GitClobbered").
team_mates.[i].player_info.player_icon	String	URL of the teammate's icon (e.g., /rivals/players/heads/player_head_30000045.png).
team_mates.[i].player_info.player_uid	Number	Unique ID for the teammate (e.g., 1005053199).
heroes_ranked	Array	Contains the player's ranked hero statistics.
heroes_ranked.[i].hero_id	Number	Unique ID for the hero (e.g., 1002).
heroes_ranked.[i].hero_name	String	Name of the hero (e.g., "powerfist").
heroes_ranked.[i].level	Number	Hero's level (e.g., 7).
heroes_ranked.[i].matches	Number	Number of matches with the hero (e.g., 8).
heroes_ranked.[i].wins	Number	Number of wins with the hero (e.g., 4).
heroes_unranked	Array	Contains the player's unranked hero statistics.
heroes_unranked.[i].hero_id	Number	Unique ID for the hero (e.g., 1002).
heroes_unranked.[i].hero_name	String	Name of the hero (e.g., "powerfist").
heroes_unranked.[i].level	Number	Hero's level (e.g., 7).
heroes_unranked.[i].matches	Number	Number of unranked matches with the hero (e.g., 15).
heroes_unranked.[i].wins	Number	Number of unranked wins with the hero (e.g., 8).
maps	Array	Contains the player's map statistics.
maps.[i].map_id	Number	Unique ID for the map (e.g., 10).
maps.[i].map_name	String	Name of the map (e.g., "Double Bluff").
maps.[i].matches	Number	Number of matches on the map (e.g., 30).
maps.[i].wins	Number	Number of wins on the map (e.g., 14).
maps.[i].win_rate	String	Win rate on the map (e.g., "46.67").