Dota 2 API: Match History

Finding out which people recently picked Riki

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:

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:

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:

Breaking Down the GetMatchHistory Response

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

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:

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
6241544810 Tue Oct 26 2021 03:12:44 GMT+0000 (Coordinated Universal Time)
6241543188 Tue Oct 26 2021 03:10:12 GMT+0000 (Coordinated Universal Time)
6241542109 Tue Oct 26 2021 03:08:38 GMT+0000 (Coordinated Universal Time)
6241541827 Tue Oct 26 2021 03:07:42 GMT+0000 (Coordinated Universal Time)
6241541582 Tue Oct 26 2021 03:07:27 GMT+0000 (Coordinated Universal Time)
6241541422 Tue Oct 26 2021 03:07:37 GMT+0000 (Coordinated Universal Time)
6241541149 Tue Oct 26 2021 03:07:07 GMT+0000 (Coordinated Universal Time)
6241541074 Tue Oct 26 2021 03:07:07 GMT+0000 (Coordinated Universal Time)
6241540495 Tue Oct 26 2021 03:06:17 GMT+0000 (Coordinated Universal Time)
6241540342 Tue Oct 26 2021 03:05:57 GMT+0000 (Coordinated Universal Time)

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.