Heroes

Classes related to hero data in the API.

Bases: Model

Represents a hero character in Marvel Rivals.

Attributes:

Name	Type	Description
id	str	Unique hero identifier.
name	str	Hero's display name.
real_name	str	The hero's real-world identity.
imageUrl	str	URL or path to the hero's image.
role	str	The hero's role (e.g., Vanguard, Support).
attack_type	str	Hero's attack type (e.g., Melee Heroes).
team	list[str]	Factions or affiliations the hero belongs to (e.g., Avengers).
difficulty	str	Difficulty rating of the hero (e.g., "4").
bio	str	Short biography of the hero.
lore	str	Extended lore/backstory of the hero.
transformations	list[Transformation]	Different forms the hero can transform into.
costumes	list[Costume]	List of hero costumes/skins.
abilities	list[Ability]	List of the hero's abilities.
raw_dict	dict	The original JSON data used to create this instance.

Source code in marvelrivalsapi\models.py

@define(kw_only=True)
class Hero(Model):
    """
    Represents a hero character in Marvel Rivals.

    Attributes
    ----------
    id : str
        Unique hero identifier.
    name : str
        Hero's display name.
    real_name : str
        The hero's real-world identity.
    imageUrl : str
        URL or path to the hero's image.
    role : str
        The hero's role (e.g., Vanguard, Support).
    attack_type : str
        Hero's attack type (e.g., Melee Heroes).
    team : list[str]
        Factions or affiliations the hero belongs to (e.g., Avengers).
    difficulty : str
        Difficulty rating of the hero (e.g., "4").
    bio : str
        Short biography of the hero.
    lore : str
        Extended lore/backstory of the hero.
    transformations : list[Transformation]
        Different forms the hero can transform into.
    costumes : list[Costume]
        List of hero costumes/skins.
    abilities : list[Ability]
        List of the hero's abilities.
    raw_dict : dict
        The original JSON data used to create this instance.
    """

    id: str
    name: str
    real_name: str
    imageUrl: str
    role: str
    attack_type: str
    team: list[str] = field(factory=list)
    difficulty: str
    bio: str
    lore: str
    transformations: list[Transformation] = field(factory=list)
    costumes: list[Costume] = field(factory=list)
    abilities: list[Ability] = field(factory=list)
    raw_dict: dict[str, typing.Any] = field(factory=dict)

    @classmethod
    def from_dict(cls, data: dict[str, typing.Any]) -> Hero:
        return cls(
            id=data["id"],
            name=data["name"],
            real_name=data["real_name"],
            imageUrl=data["imageUrl"],
            role=data["role"],
            attack_type=data["attack_type"],
            team=data.get("team", []),
            difficulty=data["difficulty"],
            bio=data["bio"],
            lore=data["lore"],
            transformations=[
                Transformation.from_dict(t) for t in data.get("transformations", [])
            ],
            costumes=[Costume.from_dict(c) for c in data.get("costumes", [])],
            abilities=[Ability.from_dict(a) for a in data.get("abilities", [])],
            raw_dict=data.copy(),
        )

Bases: Model

Represents a hero ability in Marvel Rivals.

Attributes:

Name	Type	Description
id	int	Unique ability identifier.
icon	str | None	Icon path for the ability.
name	str | None	Name of the ability.
type	str	Type of the ability (e.g., Ultimate, Passive).
isCollab	bool	Whether the ability is from a collaboration.
description	str | None	Description of what the ability does.
transformation_id	str	ID of the transformation this ability is tied to.
additional_fields	dict	Dynamic key-value object with extra metadata. Keys vary per ability and may include: Key, Casting, Cooldown, Energy Cost, Special Effect, etc.
raw_dict	dict	The original JSON data used to create this instance.

Source code in marvelrivalsapi\models.py

@define(kw_only=True)
class Ability(Model):
    """
    Represents a hero ability in Marvel Rivals.

    Attributes
    ----------
    id : int
        Unique ability identifier.
    icon : str | None
        Icon path for the ability.
    name : str | None
        Name of the ability.
    type : str
        Type of the ability (e.g., Ultimate, Passive).
    isCollab : bool
        Whether the ability is from a collaboration.
    description : str | None
        Description of what the ability does.
    transformation_id : str
        ID of the transformation this ability is tied to.
    additional_fields : dict
        Dynamic key-value object with extra metadata. Keys vary per ability
        and may include: Key, Casting, Cooldown, Energy Cost, Special Effect, etc.
    raw_dict : dict
        The original JSON data used to create this instance.
    """

    id: int
    icon: str | None
    name: str | None
    type: str
    isCollab: bool
    description: str | None
    transformation_id: str
    additional_fields: dict[str, object] = field(factory=dict)
    raw_dict: dict[str, typing.Any] = field(factory=dict)

    @classmethod
    def from_dict(cls, data: dict[str, typing.Any]) -> Ability:
        return cls(
            id=data["id"],
            icon=data.get("icon"),
            name=data.get("name"),
            type=data["type"],
            isCollab=data["isCollab"],
            description=data.get("description"),
            transformation_id=data["transformation_id"],
            additional_fields=data.get("additional_fields", {}),
            raw_dict=data.copy(),
        )

Bases: Model

Represents a hero transformation in Marvel Rivals.

Attributes:

Name	Type	Description
id	str	Unique identifier for the transformation.
name	str	Name of the transformation (e.g., Bruce Banner).
icon	str	Image path for the transformation.
health	str | None	Health for the transformation, if available.
movement_speed	str | None	Movement speed in meters per second (e.g., "6m/s").
raw_dict	dict	The original JSON data used to create this instance.

Source code in marvelrivalsapi\models.py

@define(kw_only=True)
class Transformation(Model):
    """
    Represents a hero transformation in Marvel Rivals.

    Attributes
    ----------
    id : str
        Unique identifier for the transformation.
    name : str
        Name of the transformation (e.g., Bruce Banner).
    icon : str
        Image path for the transformation.
    health : str | None
        Health for the transformation, if available.
    movement_speed : str | None
        Movement speed in meters per second (e.g., "6m/s").
    raw_dict : dict
        The original JSON data used to create this instance.
    """

    id: str
    name: str
    icon: str
    health: str | None = None
    movement_speed: str | None = None
    raw_dict: dict[str, typing.Any] = field(factory=dict)

    @classmethod
    def from_dict(cls, data: dict[str, typing.Any]) -> Transformation:
        return cls(
            id=data["id"],
            name=data["name"],
            icon=data["icon"],
            health=data.get("health"),
            movement_speed=data.get("movement_speed"),
            raw_dict=data.copy(),
        )

Bases: Model

Represents a hero costume/skin in Marvel Rivals.

Attributes:

Name	Type	Description
id	str	Unique identifier for the costume.
name	str	Name of the costume.
icon	str	Icon path for the costume.
quality	str	Quality level (e.g., NO_QUALITY).
description	str	Description of the costume.
appearance	str	Visual details about the costume appearance.
raw_dict	dict	The original JSON data used to create this instance.

Source code in marvelrivalsapi\models.py

@define(kw_only=True)
class Costume(Model):
    """
    Represents a hero costume/skin in Marvel Rivals.

    Attributes
    ----------
    id : str
        Unique identifier for the costume.
    name : str
        Name of the costume.
    icon : str
        Icon path for the costume.
    quality : str
        Quality level (e.g., NO_QUALITY).
    description : str
        Description of the costume.
    appearance : str
        Visual details about the costume appearance.
    raw_dict : dict
        The original JSON data used to create this instance.
    """

    id: str
    name: str
    icon: str
    quality: str
    description: str
    appearance: str
    raw_dict: dict[str, typing.Any] = field(factory=dict)

    @classmethod
    def from_dict(cls, data: dict[str, typing.Any]) -> Costume:
        return cls(
            id=data["id"],
            name=data["name"],
            icon=data["icon"],
            quality=data.get("quality", "NO_QUALITY"),
            description=data["description"],
            appearance=data["appearance"],
            raw_dict=data.copy(),
        )

Bases: Model

Represents statistics for a hero in Marvel Rivals.

Attributes:

Name	Type	Description
hero_id	int	Unique identifier for the hero.
hero_name	str	Display name of the hero.
hero_icon	str	Path or URL to the hero's icon image.
matches	int	Total number of matches the hero has been played in.
wins	int	Total number of matches won with this hero.
k	float	Average kills per match.
d	float	Average deaths per match.
a	float	Average assists per match.
play_time	str	Total play time with this hero (formatted as hours, minutes, and seconds).
total_hero_damage	int	Total damage dealt to enemy heroes.
total_hero_heal	int	Total healing done by this hero.
total_damage_taken	int	Total damage taken while playing this hero.
session_hit_rate	float	Hit rate during sessions, usually a value between 0 and 1.
solo_kill	float	Average number of solo kills per match.
raw_dict	dict	The original JSON data used to create this instance.

Source code in marvelrivalsapi\models.py

@define(kw_only=True)
class HeroStat(Model):
    """
    Represents statistics for a hero in Marvel Rivals.

    Attributes
    ----------
    hero_id : int
        Unique identifier for the hero.
    hero_name : str
        Display name of the hero.
    hero_icon : str
        Path or URL to the hero's icon image.
    matches : int
        Total number of matches the hero has been played in.
    wins : int
        Total number of matches won with this hero.
    k : float
        Average kills per match.
    d : float
        Average deaths per match.
    a : float
        Average assists per match.
    play_time : str
        Total play time with this hero (formatted as hours, minutes, and seconds).
    total_hero_damage : int
        Total damage dealt to enemy heroes.
    total_hero_heal : int
        Total healing done by this hero.
    total_damage_taken : int
        Total damage taken while playing this hero.
    session_hit_rate : float
        Hit rate during sessions, usually a value between 0 and 1.
    solo_kill : float
        Average number of solo kills per match.
    raw_dict : dict
        The original JSON data used to create this instance.
    """

    hero_id: int
    hero_name: str
    hero_icon: str
    matches: int
    wins: int
    k: float
    d: float
    a: float
    play_time: str
    total_hero_damage: int
    total_hero_heal: int
    total_damage_taken: int
    session_hit_rate: float
    solo_kill: float
    raw_dict: dict[str, typing.Any] = field(factory=dict)

    @classmethod
    def from_dict(cls, data: dict[str, typing.Any]) -> HeroStat:
        """
        Create a HeroStat instance from a dictionary.

        Parameters
        ----------
        data : dict
            Dictionary containing hero statistics data.

        Returns
        -------
        HeroStat
            A new HeroStat instance.
        """
        return cls(
            hero_id=data["hero_id"],
            hero_name=data["hero_name"],
            hero_icon=data["hero_icon"],
            matches=data["matches"],
            wins=data["wins"],
            k=data["k"],
            d=data["d"],
            a=data["a"],
            play_time=data["play_time"],
            total_hero_damage=data["total_hero_damage"],
            total_hero_heal=data["total_hero_heal"],
            total_damage_taken=data["total_damage_taken"],
            session_hit_rate=data["session_hit_rate"],
            solo_kill=data["solo_kill"],
            raw_dict=data.copy(),
        )

    @property
    def win_rate(self) -> float:
        """
        Calculate win rate for this hero.

        Returns
        -------
        float
            Win rate as a decimal between 0 and 1.
        """
        return self.wins / self.matches if self.matches > 0 else 0.0

    @property
    def kda(self) -> float:
        """
        Calculate KDA (Kills + Assists / Deaths) ratio.

        Returns
        -------
        float
            KDA ratio. Returns (K+A) if deaths is 0.
        """
        return (self.k + self.a) / (self.d or 1)

kda property

Calculate KDA (Kills + Assists / Deaths) ratio.

Returns:

Type	Description
float	KDA ratio. Returns (K+A) if deaths is 0.

win_rate property

Calculate win rate for this hero.

Returns:

Type	Description
float	Win rate as a decimal between 0 and 1.

from_dict(data) classmethod

Create a HeroStat instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict	Dictionary containing hero statistics data.	required

Returns:

Type	Description
HeroStat	A new HeroStat instance.

Source code in marvelrivalsapi\models.py

@classmethod
def from_dict(cls, data: dict[str, typing.Any]) -> HeroStat:
    """
    Create a HeroStat instance from a dictionary.

    Parameters
    ----------
    data : dict
        Dictionary containing hero statistics data.

    Returns
    -------
    HeroStat
        A new HeroStat instance.
    """
    return cls(
        hero_id=data["hero_id"],
        hero_name=data["hero_name"],
        hero_icon=data["hero_icon"],
        matches=data["matches"],
        wins=data["wins"],
        k=data["k"],
        d=data["d"],
        a=data["a"],
        play_time=data["play_time"],
        total_hero_damage=data["total_hero_damage"],
        total_hero_heal=data["total_hero_heal"],
        total_damage_taken=data["total_damage_taken"],
        session_hit_rate=data["session_hit_rate"],
        solo_kill=data["solo_kill"],
        raw_dict=data.copy(),
    )

Bases: Model

Represents ranking information for a player in the current season.

Attributes:

Name	Type	Description
rank_game_id	int	ID of the ranked game mode.
level	int	Current rank level.
rank_score	str	Current rank score.
max_level	int	Highest rank level achieved during the season.
max_rank_score	str	Highest rank score achieved during the season.
update_time	int	Last update timestamp (Unix time).
win_count	int	Number of ranked wins.
protect_score	int	Score protected due to rank protection mechanics.
diff_score	str	Score change since the last update.
raw_dict	dict	The original JSON data used to create this instance.

Source code in marvelrivalsapi\models.py

@define(kw_only=True)
class RankSeason(Model):
    """
    Represents ranking information for a player in the current season.

    Attributes
    ----------
    rank_game_id : int
        ID of the ranked game mode.
    level : int
        Current rank level.
    rank_score : str
        Current rank score.
    max_level : int
        Highest rank level achieved during the season.
    max_rank_score : str
        Highest rank score achieved during the season.
    update_time : int
        Last update timestamp (Unix time).
    win_count : int
        Number of ranked wins.
    protect_score : int
        Score protected due to rank protection mechanics.
    diff_score : str
        Score change since the last update.
    raw_dict : dict
        The original JSON data used to create this instance.
    """

    rank_game_id: int
    level: int
    rank_score: str
    max_level: int
    max_rank_score: str
    update_time: int
    win_count: int
    protect_score: int
    diff_score: str
    raw_dict: dict[str, typing.Any] = field(factory=dict)

    @classmethod
    def from_dict(cls, data: dict[str, typing.Any]) -> RankSeason:
        """
        Create a RankSeason instance from a dictionary.

        Parameters
        ----------
        data : dict
            Dictionary containing rank season data.

        Returns
        -------
        RankSeason
            A new RankSeason instance.
        """
        if not data:
            return cls(
                rank_game_id=0,
                level=0,
                rank_score="0",
                max_level=0,
                max_rank_score="0",
                update_time=0,
                win_count=0,
                protect_score=0,
                diff_score="0",
                raw_dict=data.copy(),
            )

        return cls(
            rank_game_id=data["rank_game_id"],
            level=data["level"],
            rank_score=data["rank_score"],
            max_level=data["max_level"],
            max_rank_score=data["max_rank_score"],
            update_time=data["update_time"],
            win_count=data["win_count"],
            protect_score=data["protect_score"],
            diff_score=data["diff_score"],
            raw_dict=data.copy(),
        )

    @property
    def last_updated(self) -> datetime:
        """
        Get the last update time as a datetime object.

        Returns
        -------
        datetime
            The last time the rank was updated.
        """
        return datetime.fromtimestamp(self.update_time)

last_updated property

Get the last update time as a datetime object.

Returns:

Type	Description
datetime	The last time the rank was updated.

from_dict(data) classmethod

Create a RankSeason instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict	Dictionary containing rank season data.	required

Returns:

Type	Description
RankSeason	A new RankSeason instance.

Source code in marvelrivalsapi\models.py

@classmethod
def from_dict(cls, data: dict[str, typing.Any]) -> RankSeason:
    """
    Create a RankSeason instance from a dictionary.

    Parameters
    ----------
    data : dict
        Dictionary containing rank season data.

    Returns
    -------
    RankSeason
        A new RankSeason instance.
    """
    if not data:
        return cls(
            rank_game_id=0,
            level=0,
            rank_score="0",
            max_level=0,
            max_rank_score="0",
            update_time=0,
            win_count=0,
            protect_score=0,
            diff_score="0",
            raw_dict=data.copy(),
        )

    return cls(
        rank_game_id=data["rank_game_id"],
        level=data["level"],
        rank_score=data["rank_score"],
        max_level=data["max_level"],
        max_rank_score=data["max_rank_score"],
        update_time=data["update_time"],
        win_count=data["win_count"],
        protect_score=data["protect_score"],
        diff_score=data["diff_score"],
        raw_dict=data.copy(),
    )

Bases: Model

Represents a leaderboard with multiple players.

Attributes:

Name	Type	Description
players	list[LeaderboardPlayer]	List of players on the leaderboard.
raw_dict	dict	The original JSON data used to create this instance.

Source code in marvelrivalsapi\models.py

@define(kw_only=True)
class HeroLeaderboard(Model):
    """
    Represents a leaderboard with multiple players.

    Attributes
    ----------
    players : list[LeaderboardPlayer]
        List of players on the leaderboard.
    raw_dict : dict
        The original JSON data used to create this instance.
    """

    players: list[LeaderboardPlayer] = field(factory=list)
    raw_dict: dict[str, typing.Any] = field(factory=dict)

    @classmethod
    def from_dict(cls, data: dict[str, typing.Any]) -> HeroLeaderboard:
        """
        Create a Leaderboard instance from a dictionary.

        Parameters
        ----------
        data : dict
            Dictionary containing leaderboard data.

        Returns
        -------
        Leaderboard
            A new Leaderboard instance.
        """
        return cls(
            players=[
                LeaderboardPlayer.from_dict(player)
                for player in data.get("players", [])
            ],
            raw_dict=data.copy(),
        )

    def top_players(self, limit: int = 10) -> list[LeaderboardPlayer]:
        """
        Get the top players from the leaderboard.

        Parameters
        ----------
        limit : int, optional
            Number of top players to return, by default 10

        Returns
        -------
        list[LeaderboardPlayer]
            List of top players, limited by the specified number.
        """
        return self.players[:limit]

    def sort_by_wins(self) -> list[LeaderboardPlayer]:
        """
        Sort players by number of wins (descending).

        Returns
        -------
        list[LeaderboardPlayer]
            List of players sorted by wins.
        """
        return sorted(self.players, key=lambda p: p.wins, reverse=True)

    def sort_by_kda(self) -> list[LeaderboardPlayer]:
        """
        Sort players by KDA ratio (descending).

        Returns
        -------
        list[LeaderboardPlayer]
            List of players sorted by KDA.
        """
        return sorted(self.players, key=lambda p: p.kda, reverse=True)

    def sort_by_rank(self) -> list[LeaderboardPlayer]:
        """
        Sort players by rank level (descending).

        Returns
        -------
        list[LeaderboardPlayer]
            List of players sorted by rank level.
        """
        return sorted(
            self.players, key=lambda p: p.info.rank_season.level, reverse=True
        )

from_dict(data) classmethod

Create a Leaderboard instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict	Dictionary containing leaderboard data.	required

Returns:

Type	Description
Leaderboard	A new Leaderboard instance.

Source code in marvelrivalsapi\models.py

@classmethod
def from_dict(cls, data: dict[str, typing.Any]) -> HeroLeaderboard:
    """
    Create a Leaderboard instance from a dictionary.

    Parameters
    ----------
    data : dict
        Dictionary containing leaderboard data.

    Returns
    -------
    Leaderboard
        A new Leaderboard instance.
    """
    return cls(
        players=[
            LeaderboardPlayer.from_dict(player)
            for player in data.get("players", [])
        ],
        raw_dict=data.copy(),
    )

sort_by_kda()

Sort players by KDA ratio (descending).

Returns:

Type	Description
list[LeaderboardPlayer]	List of players sorted by KDA.

Source code in marvelrivalsapi\models.py

def sort_by_kda(self) -> list[LeaderboardPlayer]:
    """
    Sort players by KDA ratio (descending).

    Returns
    -------
    list[LeaderboardPlayer]
        List of players sorted by KDA.
    """
    return sorted(self.players, key=lambda p: p.kda, reverse=True)

sort_by_rank()

Sort players by rank level (descending).

Returns:

Type	Description
list[LeaderboardPlayer]	List of players sorted by rank level.

Source code in marvelrivalsapi\models.py

def sort_by_rank(self) -> list[LeaderboardPlayer]:
    """
    Sort players by rank level (descending).

    Returns
    -------
    list[LeaderboardPlayer]
        List of players sorted by rank level.
    """
    return sorted(
        self.players, key=lambda p: p.info.rank_season.level, reverse=True
    )

sort_by_wins()

Sort players by number of wins (descending).

Returns:

Type	Description
list[LeaderboardPlayer]	List of players sorted by wins.

Source code in marvelrivalsapi\models.py

def sort_by_wins(self) -> list[LeaderboardPlayer]:
    """
    Sort players by number of wins (descending).

    Returns
    -------
    list[LeaderboardPlayer]
        List of players sorted by wins.
    """
    return sorted(self.players, key=lambda p: p.wins, reverse=True)

top_players(limit=10)

Get the top players from the leaderboard.

Parameters:

Name	Type	Description	Default
limit	int	Number of top players to return, by default 10	10

Returns:

Type	Description
list[LeaderboardPlayer]	List of top players, limited by the specified number.

Source code in marvelrivalsapi\models.py

def top_players(self, limit: int = 10) -> list[LeaderboardPlayer]:
    """
    Get the top players from the leaderboard.

    Parameters
    ----------
    limit : int, optional
        Number of top players to return, by default 10

    Returns
    -------
    list[LeaderboardPlayer]
        List of top players, limited by the specified number.
    """
    return self.players[:limit]