THINGS YOU SHOULD KNOW BEFORE STARTING

[MuppetMaster42]

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.

BEGIN BY READING THE TERMS AND CONDITIONS OF STEAM'S WEBAPI BY CLICKING HERE


THE API CANNOT BE USED TO GET PRIVATE MATCHES

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.

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

• For a full list of available calls, see http://wiki.teamfortress.com/wiki/WebAPI#Dota_2

Common options:
Note that unless otherwise stated, an option's default is empty/ignored.

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:

<path to steam>/Steam/steamapps/common/dota 2 beta/dota/pak01_dir.vpk

Then inside this file, they can be found in

root\resource\flash3\images\

OR get high-quality images from the steam servers:

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:

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)

<suffix> = eb.png

2) small horizontal portrait - 59x33px

<suffix> = sb.png

3) large horizontal portrait - 205x11px

<suffix> = lg.png

4) full quality horizontal portrait - 256x114px

<suffix> = full.png

5) full quality vertical portrait - 234x272px (note this is a .jpg)

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

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:

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:

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:

• New functionality as per http://www.joindota.com/en/news/6545...er-file-layout
• items in VPK as per http://dev.dota2.com/showthread.php?...ight=items.txt (thanks to alcaras)
• fantasy API

[mmayboroda]

Thanks for this MuppetMaster42!!!

[Shinkai]

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.

[budswarez]

Good bro tnks for share! will help me a lot!

[walkingcarpet]

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.

[RJackson]

How do I get a player's 32- or 64-bit SteamID?
If you look at the player's page

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.

[MuppetMaster42]

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

[MuppetMaster42]

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..

[GeoStrik3r]

thanks but you forgot to add "its not working since over a month"

[56k_Rockstar]

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
    $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