rivals-api 3.0.0

Typed match references and combined match details now make history rows directly usable in bot messages and lazy detail lookups.

Changes

• Added match.get_details(refresh=False) to history matches. It fetches combined RivalsData, RivalsTracker, and Tracker.gg details with typed teams, players, and hero statistics.
• Added named map, queue, gameplay, platform, rank, season, and hero references. Map variant 1288 displays as Hell's Heaven, with Hydra Charteris Base available as its location. Names resolve locally using 118 map variants and 20 observed seasons; unknown codes remain explicit.
• Added normalized accuracy_percent for players and heroes. Session hit rate remains separate from accuracy, and invalid/NaN values are treated as unavailable.
• Preserved provider responses, field provenance, conflicts, failures, and completeness. Ambiguous player identities remain visible instead of being combined by row order.
• Added refresh support and retry behavior for partial details, plus missing map/queue/platform/season context retained from the same history match.

Migration from 2.x

match.platform is now a typed Platform, rather than a numeric value. Use match.platform.id or match.platform_id for the original number.

print(match.map)           # Hell's Heaven
print(match.map.name)      # Hell's Heaven (plain string)
print(match.map.id)        # 1288
print(match.game_mode)     # Custom
print(match.gameplay_mode) # Domination
print(match.platform)      # PC

References format as names and retain their IDs. Serialized matches include structured reference objects alongside legacy numeric fields; .raw preserves the input payload. Gameplay names come from the map/objective context, rather than assuming a universal meaning for the raw gameplay code.

See readable references and migration and combined match details.

Validation

106 tests passed; Ruff passed; wheel and source distribution built successfully. The packaged catalogs were verified from the built wheel.

python -m pip install --upgrade rivals-api

rivals-api 2.1.0

What's new

• Match history now requires a limit: fetch a bounded, resumable set or all available pages, with cross-provider deduplication.
• Added overall, hero, and class win-rate methods with fast provider estimates, exact match-history calculations, and request-free reuse of cached full history.
• Added MCP player search candidates and numeric UID profile lookup.
• Updated documentation and migration/release notes.

Exact hero and class rates may fetch match details per match; provider coverage and attribution fallbacks are included in results.

See the changelog.

rivals-api 2.0.0

Changelog

2.0.0 — 2026-10-02

This release changes the project from a RivalsData-only wrapper into rivals-api,
a multi-source Marvel Rivals stats client and read-only tracker. RivalsData,
RivalsTracker, and Tracker.gg are used where their public data overlaps; provider
specific endpoints remain available when their data does not overlap.

Package and migration

• PyPI distribution: rivals-api (previously rivalsdata-api).

• Preferred import: rivals_api (previously rivalsdata).

• Preferred client: RivalsClient (previously RivalsDataClient).

• RivalsDataClient, RivalsDataError, and RivalsDataHTTPError remain exported
  aliases. The rivalsdata module path also forwards imports to rivals_api.

• To avoid two installed distributions owning the same compatibility files,
  remove the old distribution before installing the renamed one:

  python -m pip uninstall rivalsdata-api
  python -m pip install rivals-api

  Install optional features with rivals-api[browser] or rivals-api[mcp].

Provider integration and data selection

• Existing player, match, hero, rank, and live-game methods can enrich RivalsData
  results with public RivalsTracker and Tracker.gg data. Set enrich=False for
  the original RivalsData-only request behavior.
• Provider requests use separate transports and caches. The optional Camoufox
  fallback supports sites that reject a normal HTTP session. Provider failures,
  privacy limits, freshness and source coverage remain visible to callers.
• Comparable values are selected using validity, player/match/season/mode scope,
  units, verified update times, completed-detail coverage, and agreement between
  distinct providers. Original alternatives and selection explanations remain
  in provider_metadata.
• Match counts, wins and losses are selected together. Derived win rates,
  averages and totals follow the selected match population instead of mixing
  incompatible samples. Rank-system match counts and separately reported career
  counts are preserved as different measures.
• Match history can combine provider pages, preserve opaque per-source cursors,
  deduplicate match IDs, and apply filters consistently. Match details are
  joined by player/hero identity and rejected when the match IDs disagree.
• Tracker.gg time fields are normalized only when their display metadata states
  the unit. Damage taken is not silently relabeled as damage blocked.

Expanded client features

• Added provider-specific rank timelines, cosmetics, player encounters, richer
  career and hero analytics, global rank/leaderboard analytics, and public
  community listings.
• Added a packaged, dated 56-hero reference catalog, hero name/ID resolution,
  and names on typed player and match data.
• Expanded the read-only MCP server with player dashboards, match and hero
  analytics, rank-history and community tools. It supports local stdio and
  Streamable HTTP deployments.
• Added provider comparisons, API audits, captured fixtures, and documented
  data-quality limitations in docs/.

Scope and known gaps

• These sources are community/third-party or undocumented APIs and may change;
  profiles can be private, old, incomplete, or disagree on field definitions.
• Live Custom-game discovery is not implemented. Existing live match methods
  only return matches exposed by their current providers; a source listing past
  Custom matches does not establish a live Custom feed.
• Custom game history may be available on some tracker profiles, but coverage
  varies by player and provider. The source research and examples are linked in
  docs/PROVIDER_FEATURE_GAPS.md and docs/PROVIDER_INTEGRATION.md.
• The package is read-only. It does not edit player accounts, post community
  listings, vote on community content, or access private profile data.

Earlier releases

See the GitHub release history
for versions published under the former rivalsdata-api project name.

RivalsData API 1.3.0

Hero stats mode selection and leaderboard rank

Detailed player hero stats now require an explicit mode and follow the selected
website tab's ordering.

competitive = player.stats.heroes(mode="competitive", season="all")
quickplay = player.stats.heroes(mode="quickplay", season=20)
print(competitive[0].competitive.games)
print(competitive[0].rank)  # Source hero leaderboard position, or None

Migration

• Update existing player.stats.heroes(...) calls to supply
  mode="competitive" or mode="quickplay".
• MCP get_player_stats requires mode when category="heroes".
• Hero results contain only the selected mode's nested data and a mode label.
  Heroes without that mode's data are omitted. Rows are sorted by the selected
  mode's games played descending; ties retain source order.

Hero rank

Every detailed hero row exposes rank, the source's top-level leaderboard
position shown as #N in the profile's left-hand hero card. Missing positions
return None (JSON null). This rank is preserved from the source, not recalculated
for Quickplay or All Seasons. Both hero endpoints returned Loki rank 408 for
GS-, matching the card during the 2026-10-01 browser investigation.

The website receives both modes together, then filters and sorts locally.
The wrapper now follows that behavior. README, API docs, MCP descriptions,
and project context document the required mode, ordering, and rank.

Class stats still return separate totals for both modes and support individual
seasons and All Seasons. Hero summaries retain their existing behavior.

RivalsData API 1.2.3

Clarifies calculated class win-rate scope and includes metadata describing the source, formula, requested season scope, exclusions, and limitations.

RivalsData API 1.2.2

Clarifies that the player overview's overall win rate is the current competitive
season's win rate, using the latest available season with usable counts when
there is no direct source rate. It does not aggregate across seasons.

• Updates the Player.win_rate docstring, README, API inventory, and project
  context to explain the season scope.
• Updates MCP overview and dashboard descriptions.
• Labels the dashboard percentage as "season win rate".

Win-rate calculations and the existing per-season/all-seasons hero and class
selectors retain their behavior.

Validation: all 16 tests, Ruff checks, and source/wheel builds pass.

RivalsData API 1.2.1

Player class statistics now accept a numeric season ID or season="all" for
combined all-seasons data, matching the player hero summary selector.

player.stats.classes(season=20)
player.stats.classes(season="all")

The detailed player.stats.heroes method and MCP get_player_stats tool also
accept season="all". The wrapper sends the upstream all-seasons selector
(-1); omitting the season preserves the endpoint default.

Validation: all 16 tests pass, including selector forwarding and the MCP input
schema; Ruff checks and source/wheel builds pass.

RivalsData API 1.2.0

Adds calculated player statistics for tank, support, and DPS through
player.stats.classes(season=...) and the MCP get_player_stats tool with
category="classes".

• Returns separate competitive and quickplay totals for games, wins, losses,
  available MVP/SVP counts, and win rates calculated from summed wins/losses.
• Includes official role names, contributing hero IDs, and excluded records
  for unknown classes or incomplete win/loss counts.
• Supports Deadpool's separate tank, DPS, and support IDs and corrects the
  previously reversed Angela and Daredevil name mappings.
• Adds typed class response models and exports HERO_CLASSES and hero_class.
• Documents Camoufox findings on match-level character playtime. No cumulative
  playtime feature is included.

Class totals count hero participation and may count one match more than once
when a player switches heroes. Empty modes have a null win rate.

Validation: 10 mocked tests pass; Ruff checks and source/wheel builds pass.

rivalsdata-api 1.1.1

Adds all-seasons player hero fetching using the verified API season selector -1.

RivalsData API 1.1.0

Adds dedicated typed classes across the public API, including matches, characters, player proficiency, leaderboards, insights, factions, and favorites. Corrects hero trend and favorites request formats. PyPI package: https://pypi.org/project/rivalsdata-api/1.1.0/