Finding out which people recently picked Riki
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 ignoredmin_players
(count): Filters the minimum number of players required in the matches to be returnedaccount_id
(ID): Searches for all matches for a given user, using their 32-bit or 64-bit Steam IDleague_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
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 responsetotal_results
: The total number of matches for this queryresults_remaining
: The total number of matches remaining for this query (total_results = results_remaining + num_results)matches
: An array of matches in this responsematch_id
: The match's unique IDmatch_seq_num
: The sequence number representing the order in which matches were recordedstart_time
: Unix timestamp of when the match beganlobby_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 Direplayers
: An array of the players for this matchaccount_id
: 32-bit Steam account ID for the playerplayer_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)
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 IDmatches_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
.
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 |
---|---|---|
5143244852 | Fri Dec 06 2019 08:48:17 GMT+0000 (UTC) |
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
5143243777 | Fri Dec 06 2019 08:47:08 GMT+0000 (UTC) |
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
5143242842 | Fri Dec 06 2019 08:46:08 GMT+0000 (UTC) |
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
5143242742 | Fri Dec 06 2019 08:46:02 GMT+0000 (UTC) |
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
5143241009 | Fri Dec 06 2019 08:44:08 GMT+0000 (UTC) |
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
5143238839 | Fri Dec 06 2019 08:41:16 GMT+0000 (UTC) |
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
5143238716 | Fri Dec 06 2019 08:41:02 GMT+0000 (UTC) |
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
5143238649 | Fri Dec 06 2019 08:41:31 GMT+0000 (UTC) |
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
5143238546 | Fri Dec 06 2019 08:41:22 GMT+0000 (UTC) |
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
5143238175 | Fri Dec 06 2019 08:40:46 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.