IVK Skill API 1.0

Getting Started

You should have received from us:

  • user_id
  • api_key
  • config_id

For most requests, you will also need to provide a match_id. This can be an arbitrary string for testing.

REST API Overview

All requests use Basic Auth:

username: {{user_id}}
password: {{api_key}}

Base URL:

https://dev.ivk.dev/v1/mmr/{{config_id}}

e.g. to test credentials with cURL (and retrieve the configuration JSON):

curl https://dev.ivk.dev/v1/mmr/{{config_id}} -u "{{user_id}}:{{api_key}}"

Sending Match Results

Send the match results as a list of JSON objects in the body of the POST request. (see the examples)

POST https://dev.ivk.dev/v1/mmr/{{config_id}}/full/player/?match_id={{match_id}}

Request Parameters

Most parameters are optional and will fall back to default values when null or omitted.

required

  • player_id (str)
    • The unique identifier of the player.

header data

  • team_id (str|int|null)

    • The local identifier of the player's team, e.g. "Team 1".
    • Default: unique team_id per player.
    • Default behavior is to treat each player as their own team, so team_id can be omitted for 1v1 or free-for-all modes.

  • party_id (str|int|null)

    • The local identifier of the player's party.
    • Default: unique party_id per player.
    • Default behavior is to treat each player as their own party, so party_id can be omitted for games that don't support parties.

pre-match data

  • mmr (float|null)
    • The MMR of the player at the start of the match (the prior MMR).
    • Default: default_mmr specified in the MMR configuration
  • played_frac (float|null)
    • The fraction of the match the player was present.
    • Default: 1.0
  • games_played (int|null)
    • The previous number of games the player has played (ever, or just this season).
    • Default: 0
    • Not necessary if placement matches are disabled in the MMR configuration, but most MMR systems should use some form of placement.

post-match data

  • player_score (float|null)
    • The player's score in this match.
    • Default: 0
    • It's up to the game to determine this value. The only requirement is that a higher score is better than a lower score.
    • This value only matters if player performance is configured to have non-zero weight.
  • team_score (float|null)
    • The player's team's score.
    • Default: the first non-null team_score for the team, otherwise the sum of the player scores on the team (e.g. total kills)
    • This value is normalized according to the MMR configuration, e.g:
      • binary outcome: { loss => 0, win => 1 }
      • margin-of-victory (considers number of rounds won, or difference in score)

optional overrides

  • outcome (float|null)[0-1]
    • For games with custom score normalization or custom player/team models
    • Default: calculated from player_score and team_score using IVK normalization and player/team performance model (recommended).
  • placement_frac (float|null)[0-1]
    • Manually calculated placement fraction
    • Default: calculated from games_played based on MMR configuration (recommended).

Response Attributes

The POST response includes summary data (see the examples) and a list of JSON objects per player in the player_list field:

  • player_id (str)
    • pass-through identifier of the player
  • mmr (float)
    • prior MMR of the player
  • mmr_team (float)
    • total MMR of the player's team as determined by the party and team models (not necessarily the sum of MMRs)
    • can be shown directly in an after-action report
  • played_frac (float)
    • pass-through value
  • placement_frac (float)
    • the prior fraction of placement matches the player completed (0-1)
  • party_size (int)
    • total number of players in the player's party
  • expected (float)
    • the combined expected outcome for the player (0-1)
    • predicted based on combined party, team, and player performance models
    • can be used indirectly in an after-action report
  • outcome (float)
    • the actual outcome for the player (0-1)
    • based on the combined the normalized player and team scores
    • can be used indirectly in an after-action report
  • player_expected (float)
    • the expected individual outcome regardless of team (0-1)
    • potentially clamped to a maximum value (typically 0.8) to guarantee minimum payoffs
  • player_expected_raw (float)
    • the unclamped player_expected value (0-1)
    • can be used indirectly in an after-action report
  • player_outcome (float)
    • the personal outcome for the player (0-1)
    • regardless of party or team factors
  • player_weight (float)
    • how much personal performance factors into the final MMR update
    • configured as a function of placement and/or mmr range
    • typically higher during placement than regular matches
  • player_contrib (float)
    • MMR change due to player performance
    • can be used in an after-action report (sometimes. carefully.)
    • can be negative even if team wins and/or mmr_delta is net positive
    • behavior depends heavily on the specific MMR configuration
  • team_expected (float)
    • the expected team outcome based on party and team model (0-1)
    • potentially clamped to a maximum value (typically 0.8) to guarantee minimum payoffs
  • team_expected_raw (float)
    • the unclamped team_expected value (0-1)
    • can be used indirectly in an after-action report
  • team_outcome (float)
    • the team outcome (0-1)
    • regardless of individual performance
  • team_weight (float)
    • how much team performance factors into the final MMR update
    • configured as a function of placement and/or mmr range
    • typically lower during placement than regular matches
    • often 1.0 after placement is complete in Ranked modes
  • team_contrib (float)
    • MMR change due to team outcome
    • can be used in an after-action report (sometimes. carefully.)
    • can have different sign than player_contrib
    • behavior depends heavily on the specific MMR configuration
  • mmr_delta (float)
    • net MMR change after this match
    • should be shown on after-action report (in Ranked modes)
  • mmr_final (float)
    • final MMR after this match
    • equivalent to mmr + mmr_delta
    • should be shown on after-action report (in Ranked modes)

Advanced

IVK Skill also has routes for calculating pre-match data, or for calculating in-match results (e.g. when a team or player is eliminated in a battle royale). BR has multiple possibilities for MMR though, including tracking separate encounter MMR (based on head-to-head kills) and survival MMR (based on time).

POST https://dev.ivk.dev/v1/mmr/{{config_id}}/pre/player/?match_id={{match_id}}
POST https://dev.ivk.dev/v1/mmr/{{config_id}}/partial/player/?match_id={{match_id}}