A WebAPI for match history is now available on Dota 2. Web developers can now retrieve the match history and match details in JSON or XML format for use in their own applications.
First off get a dev key from here, http://steamcommunity.com/dev/apikey and login with your Steam account and you will get unique key. Please do not share this key as it identifies you when you make WebAPI requests.
There are two API calls for Dota 2's match history:
Retrieving match history:
Replace "<key>" with your personal WebAPI key. That call will return the latest 25 public matches in JSON format. You can request it in XML format
A maximum of 25 matches are returned. To request the next 25, use the param "start_at_match_id" with one less than the last match number you received:
To retrieve the specific details of a match, use this API:
The following additional parameters are available on GetMatchHistory:
For example, to retrieve the latest single match:
player_name=<name> # Search matches with a player name, exact match only
hero_id=<id> # Search for matches with a specific hero being played, hero id's are in dota/scripts/npc/npc_heroes.txt in your Dota install directory
skill=<skill> # 0 for any, 1 for normal, 2 for high, 3 for very high skill
date_min=<date> # date in UTC seconds since Jan 1, 1970 (unix time format)
date_max=<date> # date in UTC seconds since Jan 1, 1970 (unix time format)
account_id=<id> # Steam account id (this is not SteamID, its only the account number portion)
league_id=<id> # matches for a particular league
start_at_match_id=<id> # Start the search at the indicated match id, descending
matches_requested=<n> # Defaults is 25 matches, this can limit to less
Please explore this functionality. We can’t wait to see what people come up with using this information.
Please do be nice and not slam the WebAPI’s too heavily, however! Thanks!
Frequently asked questions about the WebAPI:
How do I get the replay from the information in GetMatchDetails?
Replays are formed from the following URL:
The cluster, match_id and replay_salt are available from the fields in GetMatchDetails. For the curious, cluster is the server data center the game was played at.
Are match history and details going to be available for private matches?
These are not available at this time. We'll are looking at a possible OATUH based authentication system that will allow players to retrieve their match history securely and allow third party sites to get that information they grant access to. We hope to have more details soon.
How do I find out what hero_id and item values translate into?
These values can be found in files that are in your Dota 2 install directory.
Steam/steamapps/common/dota 2 beta/gamedota/scripts/npc/npc_heroes.txt
Steam/steamapps/common/dota 2 beta/gamedota/scripts/npc/items.txt
Is there a WebAPI for current games in progress?
Not yet! But this is a excellent suggestion.
Are there limits on how many API calls?
Not presently, but you may get a 503 Error if the matchmaking server is busy or you exceed limits. Please wait 30 seconds and try again. A good rule of thumb is limit your requests to about one per second.
Update From the Dota 2 Development Team
As some of you have noticed, the WebAPI is currently inaccessible. What happened was that we were seeing such an overwhelming demand from people for this information that our servers were getting completely bogged down servicing all of these requests. None of the behavior we saw was malicious, there was just way too much demand and unfortunately it really started impacting the experience of general DOTA players and therefore we had to disable it for now. This is of course super interesting information and we want to make it as available to as many people as we possibly can and we are working on a couple of solutions to help greatly improve the situation so we can handle more requests, but can’t give any definitive time frame for when these will be brought online. We will keep you posted as things develop, but hopefully our solutions will let us have our cake and eat it too (after all not all cakes are a lie).
As a side note though, if people are developing against this API, make sure to implement rate limiting within your systems. We don’t have any numbers at this point, but we of course need to prevent individual accounts from submitting thousands of requests in a small window so that we can make sure that we can handle a reasonable number of users. Also if people have specific queries that they are running in large quantities that don’t naturally fit into the existing API let us know so that if it is a common request people have that the system can efficiently handle those requests.