Announcement

Collapse

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

THINGS YOU SHOULD KNOW BEFORE STARTING

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

  • THINGS YOU SHOULD KNOW BEFORE STARTING

    This post is a constant work in progress, please see the todo list down the bottom before suggesting missing items!



    Web developers can now retrieve the match history and match details in JSON or XML format for use in their own applications.



    GETTING A KEY

    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.
    Originally posted by Zoid
    When you go to http://steamcommunity.com/dev/apikey the "domain" field is just a note. It's not actually used for anything and is just a helpful field so you can tell us what your website is. You can just put your name in for now. Once you get a key, its what uniquely identifies you when accessing our WebAPI calls.

    THE API CALLS


    Common options:
    Note that unless otherwise stated, an option's default is empty/ignored.
    Code:
    key=<key>       # Your personal API key (from above)
    language=<lang> # The language to retrieve results in (default is en_us) (see http://en.wikipedia.org/wiki/ISO_639-1 for the language codes (first two characters) and http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for the country codes (last two characters))
    format=<form>   # The format to retrieve results in ("JSON" or "XML") (default is JSON)

    GetMatchHistory
    Used to get a list of matches played.

    see: https://wiki.teamfortress.com/wiki/W...etMatchHistory


    GetMatchDetails
    Used to get detailed information about a specified match.

    see: https://wiki.teamfortress.com/wiki/W...etMatchDetails


    GetMatchHistoryBySequenceNum
    Used to get the matches in the order which they were recorded (i.e. sorted ascending by match_seq_num).
    This means that the first match on the first page of results returned by the call will be the very first public mm-match recorded in the stats.
    This API combines GetMatchHistory with GetMatchDetails - i.e. each page returned requires no additional calls for more data.

    see: https://wiki.teamfortress.com/wiki/W...yBySequenceNum


    GetHeroes
    Used to get an UP-TO-DATE list of heroes.
    Note that it is important to include a "language" parameter if you want the human-readable names of heroes.

    see: https://wiki.teamfortress.com/wiki/WebAPI/GetHeroes
    For more info, see the HEROES section below.


    GetGameItems
    Used to get an UP-TO-DATE list of in-game items.
    Note that it is important to include a "language" parameter if you want the human-readable names of items.

    see: https://wiki.teamfortress.com/wiki/WebAPI/GetGameItems
    For more info, see the ITEMS section below.


    GetLeagueListing
    Used to get a list of the tournament leagues that are available for viewing in the client (i.e. you can buy a ticket to them).
    Intended for use in conjunction with GetLiveLeagueGames.

    see: https://wiki.teamfortress.com/wiki/W...tLeagueListing


    GetLiveLeagueGames
    Used to get a list of the tournament games that are currently in progress.

    see: https://wiki.teamfortress.com/wiki/W...iveLeagueGames


    GetTeamInfoByTeamID
    Used to get data about teams that have been created in the client.
    Note that this call by default will return a list of every team (with 100 per page) sorted ascending by team_id

    see: https://wiki.teamfortress.com/wiki/W...amInfoByTeamID


    GetPlayerSummaries
    Used to get details about a player's Steam account.

    see: http://wiki.teamfortress.com/wiki/We...layerSummaries


    GetSchema
    Used to get list of economy (cosmetic) items.

    see: http://wiki.teamfortress.com/wiki/WebAPI/GetSchema

    NOTE THIS IS CURRENTLY BROKEN/NOT WORKING.
    in the mean time you can use the GetSchemaURL endpoint.

    see: https://wiki.teamfortress.com/wiki/WebAPI/GetSchemaURL
    Note that the text file linked in GetSchemaURL is in VDF, so you will have to parse this format.

    ITEMS
    Use the above GetGameItems API call to retrieve a list of item IDs

    Images
    There are two choices for this, either get the full quality images direct from the game files:
    See CyborgMatt's guide here to learn how to open a vpk file.
    the images can be found in the file:
    Code:
    <path to steam>/Steam/steamapps/common/dota 2 beta/dota/pak01_dir.vpk
    Then inside this file, they can be found in
    Code:
    root\resource\flash3\images\
    OR get high-quality images from the steam servers:
    Code:
    http://cdn.dota2.com/apps/dota2/images/items/<name>_lg.png
    where <name> is the item's "name" from the text file above, without the "item_" at the start.


    HEROES
    Use the above GetHeroes API call to retrieve a list of hero IDs

    Images
    You use the method as above in ITEMS
    OR you can get them from valve's servers:
    There are 4 different types of images, all follow the form:
    Code:
    http://cdn.dota2.com/apps/dota2/images/heroes/<name>_<suffix>
    where <name> is the hero's "name" from GetHeros, without the "npc_hero_dota_" at the start and <suffix> is one of the following:
    1) tiny horizontal portrait - 35x20px (this one is no longer available)
    Code:
    <suffix> = eb.png

    2) small horizontal portrait - 59x33px
    Code:
    <suffix> = sb.png
    3) large horizontal portrait - 205x11px
    Code:
    <suffix> = lg.png
    4) full quality horizontal portrait - 256x114px
    Code:
    <suffix> = full.png
    5) full quality vertical portrait - 234x272px (note this is a .jpg)
    Code:
    <suffix> = vert.jpg

    STEAMIDS

    The Dota2 API generally gives you people's SteamIDs as 32-bit numbers.

    In order to convert from these 32-bit numbers to Steam Names, you must first convert between the 32-bit ID and 64-bit ID:
    • On a system that supports up to 64-bit numbers you can do the following:
      • STEAMID64 - 76561197960265728 = STEAMID32
      • STEAMID32 + 76561197960265728 = STEAMID64
      • OR
      • STEAMID32 = The right-most 32-bits of STEAMID64
      • STEAMID64 = concatenate("00000001000100000000000000000001", STEAMID32);
    • On a system that only supports up to 32-bit numbers - it's trickier. You have to rely on the language's built-in "big number" functions (i.e. PHP's gmp extension: see this post for details)
    Once you have the 64-bit ID, then you can use the GetPlayerSummaries call to get their detail!


    How to get someone's 64-bit ID to search with:

    If you have their vanity URL, it should look like this:
    Code:
    http://steamcommunity.com/id/<vanity_name>/
    Using ResolveVanityURL (see http://wiki.teamfortress.com/wiki/We...solveVanityURL for more info), you can get the 64-bit ID as follows:
    [CODE]http://api.steampowered.com/ISteamUser/ResolveVanityURL/v0001/?key=<key>&vanityurl=<vanity_name>[CODE]

    If you have an ID url:
    Code:
    http://steamcommunity.com/profiles/<id>/
    Then the <id> is their 64-bit ID and you're done!

    If you have just a Steam-Name:
    You can use this to search the Dota2 API directly using the player_name option of GetMatchHistory
    You can then find their 32-bit ID in the list and then convert it to a 64-bit ID as above.


    FAQ

    Are match history and details going to be available for private matches?
    These are not available at this time. We are looking at a possible OATUH based authentication system that will allow players to retrieve their private match history securely and allow third party sites to get that information they grant access to. We hope to have more details soon.

    Is there a WebAPI for current games in progress?
    Not yet! It has been suggested, so we will just have to wait and see!

    Are there limits on how many API calls?
    • You must manually limit your requests to one request per second in order to reduce the strain on the servers
    • If you get a 503 Error: the matchmaking server is busy or you exceeded limits. Please wait 30 seconds and try again.
    • Please note that as written in the WebAPI T&C's, you are limited to 100,000 API calls per day.

    Can I persist the data in a database or similar?
    YES! In fact, it is recommended in order to reduce the strain on the server.

    What is this "Unix time"/"UTC seconds since..."?
    http://en.wikipedia.org/wiki/Unix_time

    How do I get a player's 32- or 64-bit SteamID?
    See SteamIDs above!

    How to I fetch a team's logo?
    See the example posted by DanielJ here: http://dev.dota2.com/showthread.php?...l=1#post462059
    Though the image extension is not given, it is PNG.

    I want to start developing, should I jump right into grabbing data using the API?
    Short answer; no. You should not.
    Whilst you are developing your application, it will be rather silly and inconsiderate to slam the API with calls for data you just throw away.
    In stead, consider one of two alternatives:
    1) (preferred) Manually make a few calls to the API and save the results to your hard drive, then use these to test from until you're confident your application does what it's supposed to.
    2) If you are developing your actual dynamic API calls, (first make sure you have implemented a suitable request limit as above) consider using the Dota2 Beta TEST API, which works identically to the Dota2 Beta API, except its urls are different:
    Code:
    Replace "IDOTA2Match_570" with "IDOTA2Match_205790"
    Can I create a private, unofficial league and use the API to get data for it?
    NO. You can only get publicly available data using the API, so you CANNOT get any private matches using it.

    Is there feature X in the API which will give me a set of cumulative data Y?
    NO. The only features in the API are those listed above.
    If you want to figure out the best hero, the best player, the most used hero, the most bought item or the team with the most wins, etc, etc, etc you have to use the available API calls to fetch the data, store it in a database and do the calculations yourself.


    PLEASE REPLY WITH ANY THINGS THAT ARE WRONG/THINGS I SHOULD ADD.
    THANKS



    CHANGE LOG:
    • 2012/10/11 - Created Thread.
    • 2012/10/12 - Made SteamIDs its own section, changed to using ResolveVanityURL (thanks to RJackson).
    • 2012/10/15 - Quoted Zoid's "API is down" post.
    • 2013/01/27 - Removed api is down post, added link to the api's T&C's, fixed up a few errors (thanks to sema), added to-do list.
    • 2013/01/31 - Added info about leaver_status (thanks to adrianlegg) and lobby_type (thanks to Cyborgmatt).
    • 2013/02/03 - Updated GetMatchHistory & GetMatchDetails (thanks to adrianlegg for game_mode data).
    • 2013/02/06 - Updated GetMatchHistory & GetMatchDetails with latest parameters from ISteamWebAPIUtil/GetSupportedAPIList. Added GetLeagueListing, GetLiveLeagueGames & GetMatchHistoryBySequenceNum. Added info about team logo picture files in FAQ.
    • 2013/02/07 - Added GetTeamInfoByTeamID.
    • 2013/04/03 - Changed the links which show how tower_status and barracks_status work.
    • 2014/02/19 - Updated the hero and item image urls for valve's servers.
    • 2014/04/04 - Updated FAQ.
    • 2014/04/29 - Linked out to GelioS's json data sets
    • 2015/05/04 - Added GetGameItems
    • 2016/04/12 - Removed most of the info, instead linking to the TFWiki pages (which are easier to create and maintain)

    TODO:
    Last edited by MuppetMaster42; 04-11-2016, 04:45 PM. Reason: changelog
    The API Bible: Things You Should Know Before Starting API Development

  • #2
    Thanks for this MuppetMaster42!!!

    Comment


    • #3
      Excellent tutorial. Nothing seems missing with first glance. Stickying could be useful, provided that the first post stays up-to-date with new functions and features.

      Comment


      • #4
        Good bro tnks for share! will help me a lot!

        Comment


        • #5
          This is a really great write up, thank you!

          Though if I may ask politely... please change the all caps in the title.

          edit: Also yes, this would be good to sticky.

          Comment


          • #6
            Originally posted by MuppetMaster42 View Post
            How do I get a player's 32- or 64-bit SteamID?
            If you look at the player's page
            Code:
            http://steamcommunity.com/id/<vanity_name>?xml=1
            and look for the "steamID64" field, this is their 64-bit ID.

            To convert between 64-bit and 32-bit:
            • On a system that supports up to 64-bit numbers you can do the following:
              • STEAMID64 - 299067162755072 = STEAMID32
              • STEAMID32 + 299067162755072 = STEAMID64
              • OR
              • STEAMID32 = The right-most 32-bits of STEAMID64
              • STEAMID64 = concatenate("00000001000100000000000000000001", STEAMID32);
            • On a system that only supports up to 32-bit numbers, it's trickier. You have to rely on the language's built-in "big number" functions (i.e. PHP's gmp extension: see this post for details)
            It's probably better practise to stick with API calls instead of relying on Steam Community's XML pages. If a user has a profile url of the format: http://steamcommunity.com/profile/12341234/, then 12341234 is their SteamId64; if they have a vanity url, as is your example, you can get their SteamId64 with the ISteamUser/ResolveVanityURL api call.

            Comment


            • #7
              Originally posted by RJackson View Post
              It's probably better practise to stick with API calls instead of relying on Steam Community's XML pages. If a user has a profile url of the format: http://steamcommunity.com/profile/12341234/, then 12341234 is their SteamId64; if they have a vanity url, as is your example, you can get their SteamId64 with the ISteamUser/ResolveVanityURL api call.
              Yeah, sorry, I didn't think about an API way to get it (silly me)
              I updated the post to use ResolveVanityURL
              The API Bible: Things You Should Know Before Starting API Development

              Comment


              • #8
                Originally posted by walkingcarpet View Post
                This is a really great write up, thank you!

                Though if I may ask politely... please change the all caps in the title.

                edit: Also yes, this would be good to sticky.
                Thanks

                Also, I changed the title of the original post, but I think an admin has to change the thread Title..
                The API Bible: Things You Should Know Before Starting API Development

                Comment


                • #9
                  thanks but you forgot to add "its not working since over a month"
                  -------
                  Achievement: Won at least a match with every dota2 hero
                  Fav Dev Quote: Bug is working fine
                  -------

                  Comment


                  • #10
                    So currently only the GetHeroes API call works right? Because thats the only request I get data from and the call is made to a different EndPoint (not $baseUrl but https://api.steampowered.com/IEconDOTA2_570/) and those are disabled at the moment, right?

                    I just looked into this stuff for a few minutes and called a bit against the API via PHP like this:

                    PHP Code:
                    <?php
                        $matchID 
                    "51730xyz";
                        
                    $key "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
                        
                    $baseUrl 'https://api.steampowered.com/IDOTA2Match_570/';

                        
                    /* Get Match Details */
                        
                    $url[0] = $baseUrl.'GetMatchDetails/V001/?key='.$key.'&match_id='.$matchID;    
                        

                        
                    /* Get 25 latest matches from AM */
                        
                    $url[1] = $baseUrl.'GetMatchHistory/V001/?format=JSON&language=en_us&key='.$key.'&hero_id=1';
                        

                        
                    /* Get list of up2date heroes */
                        
                    $url[2] = 'https://api.steampowered.com/IEconDOTA2_570/GetHeroes/v0001/?key='.$key.'&language=en_us&format=JSON';        


                        for(
                    $i 0$i<count($url); $i++) {
                            
                    $response file_get_contents$url[$i], $info);       // here happens the request to the api and the response is saved
                            
                    if($response != null ) {
                                
                    print_r($response);                                // print response data, its an array so for rapid coding its enough
                            
                    } else {
                            
                    print_r('empty response<br/>');
                            
                    sleep(1);                                              // to stay in the limits of 1 req per sec
                            
                    }
                        }
                    ?>

                    I'm not a big coder so please look over the quick'n'dirtyness

                    Comment


                    • #11
                      Originally posted by 56k_Rockstar View Post
                      So currently only the GetHeroes API call works right? Because thats the only request I get data from and the call is made to a different EndPoint (not $baseUrl but https://api.steampowered.com/IEconDOTA2_570/) and those are disabled at the moment, right?

                      I just looked into this stuff for a few minutes and called a bit against the API via PHP like this:

                      <snip>

                      I'm not a big coder so please look over the quick'n'dirtyness
                      This thread isn't the place for asking for help! it is merely here to display a the list of FAQ because (I for one) got sick of answering the same questions.

                      in future please post in a new thread with any questions.

                      As stated in the FAQ section above, the stats API is down until further notice, although if u want to test your algorithm the dota2 test api is still up.
                      see the original post for details.
                      The API Bible: Things You Should Know Before Starting API Development

                      Comment


                      • #12
                        Originally posted by 56k_Rockstar View Post
                        So currently only the GetHeroes API call works right? Because thats the only request I get data from and the call is made to a different EndPoint (not $baseUrl but https://api.steampowered.com/IEconDOTA2_570/) and those are disabled at the moment, right?

                        I just looked into this stuff for a few minutes and called a bit against the API via PHP like this:

                        PHP Code:
                        <?php
                            $matchID 
                        "51730xyz";
                            
                        $key "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
                            
                        $baseUrl 'https://api.steampowered.com/IDOTA2Match_570/';

                            
                        /* Get Match Details */
                            
                        $url[0] = $baseUrl.'GetMatchDetails/V001/?key='.$key.'&match_id='.$matchID;    
                            

                            
                        /* Get 25 latest matches from AM */
                            
                        $url[1] = $baseUrl.'GetMatchHistory/V001/?format=JSON&language=en_us&key='.$key.'&hero_id=1';
                            

                            
                        /* Get list of up2date heroes */
                            
                        $url[2] = 'https://api.steampowered.com/IEconDOTA2_570/GetHeroes/v0001/?key='.$key.'&language=en_us&format=JSON';        


                            for(
                        $i 0$i<count($url); $i++) {
                                
                        $response file_get_contents$url[$i], $info);       // here happens the request to the api and the response is saved
                                
                        if($response != null ) {
                                    
                        print_r($response);                                // print response data, its an array so for rapid coding its enough
                                
                        } else {
                                
                        print_r('empty response<br/>');
                                
                        sleep(1);                                              // to stay in the limits of 1 req per sec
                                
                        }
                            }
                        ?>

                        I'm not a big coder so please look over the quick'n'dirtyness

                        Don`t use file_get_contents for this kind of stuff, use curl its much faster and more efficent.

                        Comment


                        • #13
                          How I can get data of dota2 profile (not steam!) such as current player level, win rate etc. ? That even possible?

                          Comment


                          • #14
                            Originally posted by Fingerling View Post
                            How I can get data of dota2 profile (not steam!) such as current player level, win rate etc. ? That even possible?
                            there were methods of getting level/etc, but IDK if they still work...
                            to get winrate - you have to get every single one of their matches and calculate it.
                            The API Bible: Things You Should Know Before Starting API Development

                            Comment


                            • #15
                              Also.. now that i've seen some mods lurking around this sub-forum.. can one of you pretty please sticky this for me?
                              I thought a central FAQ would be the perfect thing to sticky so people have a good guide outlining how things work - rather than using search or trawling through the many pages of posts.

                              I'll get to updating it when I get back from my holiday next week.

                              Thanks.
                              The API Bible: Things You Should Know Before Starting API Development

                              Comment

                              Working...
                              X