Forum Rules

  • No flaming or derogatory remarks, directly or through insinuation.
  • No discussion, sharing or referencing illegal software such as hacks, keygen, cracks and pirated software.
  • No offensive contents, including but not limited to, racism, gore or pornography.
  • No excessive spam/meme, i.e. copious one liners in a short period of time, typing with all caps or posting meme responses (text/image).
  • No trolling, including but not limited to, flame incitation, user provocation or false information distribution.
  • No link spamming or signature advertisements for content not specific to Dota 2.
  • No Dota 2 key requests, sell, trade etc.
  • You may not create multiple accounts for any purpose, including ban evasion, unless expressly permitted by a moderator.

  • Please search before posting. One thread per issue. Do not create another thread if there is an existing one already.
  • Before posting anything, make sure you check out all sticky threads (e.g., this). Do not create new threads about closed ones.
  • It is extremely important that you post in correct forum section.

  • Balance discussion only in Misc.
  • All art related (such as hero model) feedbacks go to Art Feedback Forum.
  • All matchmaking feedback should go here: Matchmaking Feedback
  • All report/low priority issues should go here: Commend/Report/Ban Feedback
  • No specific workshop item feedback. These should go to workshop page of that item.
  • When posting in non-bugs section (such as this), use [Bugs], [Discussion] or [Suggestion] prefix in your thread name.

In case you object some action by a moderator, please contact him directly through PM and explain your concerns politely. If you are still unable to resolve the issue, contact an administrator. Do not drag these issues in public.

All rules are meant to augment common sense, please use them when not conflicted with aforementioned policies.
See more
See less

Dota 2 Match History WebAPI

This is a sticky topic.
  • Filter
  • Time
  • Show
Clear All
new posts

  • Dota 2 Match History WebAPI

    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, 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:

    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
    For example, to retrieve the latest single match:

    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.
    For heroes:
    Steam/steamapps/common/dota 2 beta/gamedota/scripts/npc/npc_heroes.txt
    For items:
    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.
    Last edited by Zoid; 09-17-2012, 10:07 AM.

  • #2
    To download a replay:

    "http://replay" + match.cluster + "" + match.match_id + "_" + match.replay_salt + ".dem.bz2?v=1"


    • #3
      Thanks, can't wait to see what the community will come up with!


      • #4
        is this going to change anything relative to or did he already have everything about this figured out beforehand?


        • #5
          Originally posted by vladhood View Post
          is this going to change anything relative to or did he already have everything about this figured out beforehand?
          I use a different method to get matches, but will most likely switch to this one


          • #6
            This is AWESOME, thank you!!


            • #7
              Question: Will we be able to use this for practice matches?


              • #8
                Wow! I finished writing my utility app to get match information and this comes into the scene. :P I'll switch over to this method for sure, as it's more stable. Can't wait!


                • #9
                  Will this have the 30day limit like the replay files?


                  • #10
                    Originally posted by The Milkman View Post
                    Question: Will we be able to use this for practice matches?

                    Originally posted by Mazungu View Post
                    Will this have the 30day limit like the replay files?


                    • #11
                      Zoid is there any way to get the WebAPI working for practice matches? NeoGAF users and I want to pull stats from our games to make an inhouse league and for use in an elo system. Being able to pull directly from match stats would make things much, much easier.


                      • #12
                        I'm hoping I can add OAUTH support in a future update so players can get their practice matches securely.


                        • #13
                          Alright, thanks for the update.


                          • #14
                            This is great, can't wait to see what the community does with it.
                            // Economy


                            • #15
                              An iPhone and android to check stats?