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
THE API CALLS
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)
Used to get a list of matches played.
Used to get detailed information about a specified match.
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.
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.
For more info, see the HEROES section below.
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.
For more info, see the ITEMS section below.
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.
Used to get a list of the tournament games that are currently in progress.
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
Used to get details about a player's Steam account.
Used to get list of economy (cosmetic) items.
NOTE THIS IS CURRENTLY BROKEN/NOT WORKING.
in the mean time you can use the GetSchemaURL endpoint.
Note that the text file linked in GetSchemaURL is in VDF, so you will have to parse this format.
Use the above GetGameItems API call to retrieve a list of item IDs
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:
Then inside this file, they can be found in
<path to steam>/Steam/steamapps/common/dota 2 beta/dota/pak01_dir.vpk
OR get high-quality images from the steam servers:
where <name> is the item's "name" from the text file above, without the "item_" at the start.
Use the above GetHeroes API call to retrieve a list of hero IDs
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:
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)
2) small horizontal portrait - 59x33px
3) large horizontal portrait - 205x11px
4) full quality horizontal portrait - 256x114px
5) full quality vertical portrait - 234x272px (note this is a .jpg)
<suffix> = full.png
<suffix> = vert.jpg
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:
Once you have the 64-bit ID, then you can use the GetPlayerSummaries call to get their detail!
- On a system that supports up to 64-bit numbers you can do the following:
- STEAMID64 - 76561197960265728 = STEAMID32
- STEAMID32 + 76561197960265728 = STEAMID64
- 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)
How to get someone's 64-bit ID to search with:
If you have their vanity URL, it should look like this:
Using ResolveVanityURL (see http://wiki.teamfortress.com/wiki/We...solveVanityURL for more info), you can get the 64-bit ID as follows:
If you have an ID url:
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.
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..."?
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:
Can I create a private, unofficial league and use the API to get data for it?
Replace "IDOTA2Match_570" with "IDOTA2Match_205790"
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.
- 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)