Dota 2 API: Match History

Getting Match History with GetMatchHistory

Now that we know how to get individual match details, let's focus on getting a list of matches played for some specified parameters. For example, you'd like to get a list of the last 10 matches where Skywrath Mage was played, and in the very high skill bracket. For a general match history call, we can make a GET request to the following URL:

https://api.steampowered.com/IDOTA2Match_570/GetMatchHistory/V001/?key=APIKEY

By default, this will return the latest 100 public matches (previously was 25) in JSON format. We can add some additional parameters to our request to filter out the types of matches we'd like returned. The following parameters are all optional:

• hero_id (ID): Allows you to search for matches where a specific hero is played; use the hero ID from GetHeroes
• game_mode (mode): Search for matches of a given mode, using the game mode ID (as of this writing, this parameter is broken, according to various complaints on the internet)
• skill (skill): Filters matches returned by skill level; 0 for any, 1 for normal, 2 for high, and 3 for very high skill (default is 0); if account_id is specified in the other parameters, this is ignored
• min_players (count): Filters the minimum number of players required in the matches to be returned
• account_id (ID): Searches for all matches for a given user, using their 32-bit or 64-bit Steam ID
• league_id (ID): Searches for matches in a particular league (league IDs are discussed in the Tournament Details section)
• start_at_match_id (ID): Starts the search at the given match ID, in descending order (older than the specified match ID)
• matches_requested (count): Sets the number of matches to be returned (default is 100)
• tournament_games_only (boolean): Set this to 1 to limit results to tournament matches and 0 to not limit results; note that tournament matches apply to games of The International from The International 4 and before

Let's construct a GET request for the last 10 matches (matches_requested=10) where Skywrath Mage was played (hero_id=101), and these matches should have a minimum of 10 players (min_players=10). We also want these to be in the very high skill bracket (skill=3). Our GET request should look like the following:

https://api.steampowered.com/IDOTA2Match_570/GetMatchHistory/V001/?key=APIKEY&matches_requested=10&hero_id=101&min_players=10&skill=3

Breaking Down the GetMatchHistory Response

As with our previous API calls, we get a JSON response back with the following fields:

• result
• status: 1 if the request was a success, and 15 if we cannot get match history for a user (because the user has not allowed it)
• statusDetail: A message explaining the status, if the status is not 1 (note the camel case)
• num_results: The number of matches in the response
• total_results: The total number of matches for this query
• results_remaining: The total number of matches remaining for this query (total_results = results_remaining + num_results)
• matches: An array of matches in this response
• match_id: The match's unique ID
• match_seq_num: The sequence number representing the order in which matches were recorded
• start_time: Unix timestamp of when the match began
• lobby_type: The match's lobby type (see lobby type)
• radiant_team_id: Team ID for the Radiant (see Tournament Details)
• dire_team_id: Team ID for the Dire
• players: An array of the players for this match
• account_id: 32-bit Steam account ID for the player
• player_slot: 8-bit unsigned integer representing the player's team and position in the team (see player slot)
• hero_id: ID of the hero played by the player (see Hero Details)

Getting Match History with GetMatchHistoryBySequenceNum

Another option for getting match history is using GetMatchHistoryBySequenceNum. This is used to get matches in the order in which they were recorded, so that they are sorted ascending by match_seq_num. The available options for this are fewer than for GetMatchHistory:

• start_at_match_seq_num (ID): The match ID at which to start the search; the search starts descending from this match ID
• matches_requested (count): Sets the number of matches to be returned (default is 100)

https://api.steampowered.com/IDOTA2Match_570/GetMatchHistoryBySequenceNum/v0001/?key=APIKEY

This is used as a GET request. The response fields follow the same format as above, for GetMatchHistory.

Displaying a List of Matches

Now that we can make an API call to get a list of matches that satisfy certain parameters, we can leverage that API call to display that list on our page and have it be up-to-date every time the page is loaded. Let's display a list of the 10 most recent Pudge matches (because apparently a lot of people play Pudge) with at least 10 players.

Let's walk through our sample code. We construct the URL like usual, and make a get request to the URL we constructed. We the parse the response body and save that as an object, and also create an array matches to store the matches we get back in the resultObj. We then go through the matches and for each match, we create an array heroes to store images of the heroes for each match (which uses a function findHero() that isn't included in the sample code; we leave this as an exercise for the reader). We push an object storing the match id and the match time (converted to human-readable time with another function convertUnixTime(), which is also left as an exercise to the reader) as well as the array of hero images onto the matches array, which is then rendered on the test page. We've hard-coded the hero ID for Pudge in this example. The result is shown below.

Match ID	Match Start Time	Heroes
5727935472	Fri Dec 04 2020 02:18:06 GMT+0000 (UTC)
5727934960	Fri Dec 04 2020 02:17:16 GMT+0000 (UTC)
5727933653	Fri Dec 04 2020 02:15:01 GMT+0000 (UTC)
5727933611	Fri Dec 04 2020 02:14:56 GMT+0000 (UTC)
5727933081	Fri Dec 04 2020 02:14:01 GMT+0000 (UTC)
5727933080	Fri Dec 04 2020 02:14:00 GMT+0000 (UTC)
5727933064	Fri Dec 04 2020 02:13:30 GMT+0000 (UTC)
5727933045	Fri Dec 04 2020 02:13:50 GMT+0000 (UTC)
5727933018	Fri Dec 04 2020 02:13:55 GMT+0000 (UTC)
5727932940	Fri Dec 04 2020 02:13:45 GMT+0000 (UTC)

Note that every time the page is loaded, a new call is made to the API, since it's pretty likely that there's been a new Pudge match every few minutes. Also note that some games may appear to have fewer than 10 heroes, which may result from players connecting but disconnecting before choosing a hero.

Some ideas for expanding on this would be to separate the heroes into Radiant and Dire, and to display other match details, which would require additional calls to GetMatchHistory, so that you can display things like gold per minute or the winner of the match, etc. Another idea would be to integrate forms into your page, so that players can select to view the last ten games played of a hero of their choosing.