Hero Stats Endpoint

This endpoint is used for gathering hero win rate, ban rate, and popularity statistics. The following attributes are returned.

With group_by_map = false
"Hero": {
    "losses": losses,
    "wins": wins,
    "bans": bans,
    "games_played": games_played,
    "win_rate": win_rate,
    "popularity": popularity,
    "ban_rate": ban_rate,
    "pick_rate": pick_rate
  }

With group_by_map = true
{
  "Map": {
    "hero": {
      "losses": losses,
      "wins": wins,
      "bans": bans,
      "games_played": games_played,
      "win_rate": win_rate,
      "popularity": popularity,
      "ban_rate": ban_rate,
      "pick_rate": pick_rate
    }
  }
}

Example Usage

{warning} All API calls require an api_token as part of the query string and are prefixed by https://api.heroesprofile.com/api

{note} When using timeframe_type=major, the group_by_map parameter is ignored and data is always aggregated across all maps.

URL Parameters (required)

mode: (json or csv)

timeframe_type:  major or minor

timeframe:  e.g, 2.47, 2.47.1.75792

game_type: Full game type.  e.g.  Storm League

hero_level: (optional) Filter by hero level. Supports multiple comma-separated values. Valid values: 1, 5, 10, 15, 20, 25, 40, 60, 80, 100. Example: hero_level=10,15,20

league_tier: (optional) Filter by league tier (0-6). Supports multiple comma-separated values. 0=Wood, 1=Bronze, 2=Silver, 3=Gold, 4=Platinum, 5=Diamond, 6=Master. Example: league_tier=4,5,6

group_by_map: true or false (only available when timeframe_type = "minor")

URL Parameters Extended Definitions

-timeframe_type: Either major or minor. major is used to gather all minor (balance) patches for a given patch cycle.

-timeframe: If major is provided as the timeframe_type, then this value needs to be the first 4 characters of the patch. e.g. 2.44, 2.46, 2.47. If minor is provided as the timeframe_type, then an actual patch value is required. e.g. 2.47.1.75792

-hero_level: (Optional) Filter results by hero level. Supports multiple values separated by commas. This allows you to see statistics for games where players were at particular hero levels. Valid values: 1, 5, 10, 15, 20, 25, 40, 60, 80, 100. Examples: hero_level=10 (single level) or hero_level=10,15,20 (multiple levels).

-league_tier: (Optional) Filter results by league tier/rank. Supports multiple values separated by commas. This allows you to see statistics for specific player skill levels. Values: 0=Wood, 1=Bronze, 2=Silver, 3=Gold, 4=Platinum, 5=Diamond, 6=Master. Examples: league_tier=5 (Diamond only) or league_tier=4,5,6 (Platinum, Diamond, and Master).

-group_by_map: This parameter groups the data by maps. If set to true, it will show the data for each hero on each map. Note: This parameter is only available when timeframe_type is set to "minor". When timeframe_type is "major", this parameter is ignored and data is always aggregated across all maps.

Example Return with group_by_map = false

{
  "Abathur": {
    "losses": 1741,
    "wins": 1520,
    "bans": 7349,
    "games_played": 3261,
    "win_rate": 46.61,
    "popularity": 25.53,
    "ban_rate": 17.68,
    "pick_rate": 7.85
  },
  "Alarak": {
    "losses": 2379,
    "wins": 2514,
    "bans": 19488,
    "games_played": 4893,
    "win_rate": 51.38,
    "popularity": 58.67,
    "ban_rate": 46.9,
    "pick_rate": 11.77
  },
  "Alexstrasza": {
    "losses": 1735,
    "wins": 1590,
    "bans": 1130,
    "games_played": 3325,
    "win_rate": 47.82,
    "popularity": 10.72,
    "ban_rate": 2.72,
    "pick_rate": 8
  },
  "Ana": {
    "losses": 2527,
    "wins": 2353,
    "bans": 7335,
    "games_played": 4880,
    "win_rate": 48.22,
    "popularity": 29.39,
    "ban_rate": 17.65,
    "pick_rate": 11.74
  },
  "Anduin": {
    "losses": 5156,
    "wins": 4513,
    "bans": 5748,
    "games_played": 9669,
    "win_rate": 46.67,
    "popularity": 37.1,
    "ban_rate": 13.83,
    "pick_rate": 23.27
  },
  "Anub'arak": {
    "losses": 2715,
    "wins": 2540,
    "bans": 5585,
    "games_played": 5255,
    "win_rate": 48.33,
    "popularity": 26.09,
    "ban_rate": 13.44,
    "pick_rate": 12.65
  },
  "Artanis": {
    "losses": 2944,
    "wins": 2984,
    "bans": 1224,
    "games_played": 5928,
    "win_rate": 50.34,
    "popularity": 17.21,
    "ban_rate": 2.95,
    "pick_rate": 14.27
  },
  "Arthas": {
    "losses": 3161,
    "wins": 3045,
    "bans": 2346,
    "games_played": 6206,
    "win_rate": 49.07,
    "popularity": 20.58,
    "ban_rate": 5.65,
    "pick_rate": 14.93
  },
  "Auriel": {
    "losses": 2727,
    "wins": 2984,
    "bans": 1443,
    "games_played": 5711,
    "win_rate": 52.25,
    "popularity": 17.22,
    "ban_rate": 3.47,
    "pick_rate": 13.74
  }
}