Dota 2 API: Tournament Details

Tournament Details

There are a number of API calls related to leagues, tournaments, and teams that we've grouped together in this section. We can use the data from these calls to supplement our calls to GetMatchHistory and GetMatchDetails, among other things.

Getting a List of Tournament Leagues with GetLeagueListing

In the Dota 2 client, there are a number of tournament leagues that viewers can buy an in-game ticket to view matches (akin to buying a ticket to see a sports match). Ticketholders can view the matches in the Dota 2 client, and depending on the tournament, are eligible for some cosmetic items. Oftentimes, sales of the tickets can contribute to the prizepools for these tournaments.

This call is intended for use in conjunction with GetLiveLeagueGames, which we will also cover in this section. Here, only the common options are available. The GET request is as follows:

https://api.steampowered.com/IDOTA2Match_570/GetLeagueListing/v0001/?key=APIKEY

GetLeagueListing Response

This one is fairly straightforward. We've omitted the response here, since it consists of 1247 leagues right now, but the breakdown is as follows:

• result
• leagues: An array of all the leagues available to view
• name: A code string for the league's full name (language-specific)
• leagueid: A unique ID for the league
• description: A description of the league (language-specific)
• tournament_url: A URL for the tournament's home page
• itemdef: An ID for an item associated with the tournament (likely the tournament ticket ID)

Getting Live Tournament Games with GetLiveLeagueGames

To be used in conjuction with GetLeagueListing, we can get a list of all tournament games being played with the following GET request. The common options are available.

https://api.steampowered.com/IDOTA2Match_570/GetLiveLeagueGames/v0001/?key=APIKEY

GetLiveLeagueGames Response

This one's a bit more substantial than GetLeagueListing; the breakdown is as follows:

• result
• games: An array containing the games
• players: An array of the players in the game
• account_id: 32-bit Steam account ID for the player
• name: The player's display name
• hero_id: The hero ID that the player is playing as (see Hero Details)
• team: The team the player is currently playing on (0 for the Radiant, 1 for the Dire, 2 for broadcaster, and 4 for unassigned)
• lobby_id: ID of the lobby for the match
• match_id: Unique match ID
• spectators: Count of spectators in the game
• series_id: ID for the game series
• game_number: The game number in the series
• league_id: Tournament league ID for which the game is being played
• stream_delay_s: Delay in seconds for streaming to spectators
• radiant_series_wins: Number of match wins that the Radiant team currently has
• dire_series_wins: Number of match wins that the Dire team currently has
• series_type
• league_series_id
• league_game_id
• stage_name
• league_tier: Likely indicates if the league is a premiere, pro, or amateur league
• scoreboard: Stores the current game scoreboard
• duration: Game length so far, in seconds
• roshan_respawn_timer: Time until Roshan respawns in the game
• radiant or dire
• score: Current kills for the corresponding team
• tower_state: See tower status
• barracks_state: See barracks status
• picks: A list of picks made by the corresponding team
• hero_id: The hero ID of the hero picked by the corresponding team
• bans: A list of bans made by the corresponding team
• hero_id: The hero ID of the hero banned by the corresponding team
• players: A list of player details
• player_slot: Position of the player in the game
• account_id: 32-bit Steam account ID for the player
• hero_id: Hero ID for the player
• kills: Current kills by the player
• deaths: Current deaths for the player
• assists: Current assists for the player
• last_hits: Current number of last hits
• denies: Current number of denies
• gold: Current gold
• level: Current level
• gold_per_min: Current gold per minute
• xp_per_min: Current experience points per minute
• ultimate_state: Indicates if the player's ultimate is available, on cooldown, out of mana, etc.
• ultimate_cooldown: Seconds left for ultimate cooldown
• item0: ID for the item in the top-left inventory slot
• item1: ID for the item in the top-center inventory slot
• item2: ID for the item in the top-right inventory slot
• item3: ID for the item in the bottom-left inventory slot
• item4: ID for the item in the bottom-center inventory slot
• item5: ID for the item in the bottom-right inventory slot
• respawn_timer: Time left on the player's respawn timer in seconds
• position_x: Player's current position in the map (x coordinate)
• position_y: Player's current position in the map (y coordinate)
• net_worth: Net worth of the player
• abilities: List of abilities for each hero
• ability_id: ID for the hero's ability
• ability_level: Current level for the hero's ability

Additional features were added to the API recently, so documentation on many of these items in GetLiveLeagueGames does not exist yet. This likely corresponded with the release of Source 2.

Getting Team Information with GetTeamInfoByTeamID

This call is used to get team information for teams that have been created in the Dota client. This is a GET request with the general format:

https://api.steampowered.com/IDOTA2Match_570/GetTeamInfoByTeamID/v001/?key=APIKEY

There are a couple additional options on top of the common options:

• start_at_team_id: The ID of the team to start at for the response teams
• teams_requested: The number of teams to return (default is 100)

As an example, we can get details about a specific team by specifying start_at_team_id and set teams_requested=1. Let's get the team with the ID 758797.

GetTeamInfoByTeamID Response

• result
• status: Indicates if the request was successful
• teams: List of teams in the response
• team_id: Unique ID for the team
• name: Team name
• tag: Team tag
• time_created: Unix timestamp of when the team was created
• rating: Indicates if the team is active or inactive
• logo: The team's logo
• logo_sponsor: The image showing the team's sponsor(s)
• country_code: Country of origin for the team
• url: Homepage for the team
• games_played_with_current_roster: Count of team matchmaking games played with the current roster
• player_N_account_id: (N >= 0) 32-bit Steam account ID of the player on the team roster
• admin_account_id: 32-bit Steam account ID for the team's administrator
• league_id_N: (N >= 0) League IDs in which the team has played

Using the Dota 2 API

Now that we've covered the API calls for getting league IDs, tournament matches being played, and team IDs, we can combine these API calls with the other calls we've covered in this how-to. However, do note that oftentimes Steam and Dota 2 APIs can be very slow or down. It is recommended that if you are making multiple API calls at once that you should store the responses if it is possible. From here, you could go through many possibilities for this web API! Like mentioned previously, you could go on to recreate your favorite match statistics website for Dota, create a Dota eSports game tracker, or your own Dota web app.

I hope you enjoyed this how-to guide to the Dota 2 web API. For comments, suggestions, complaints, and miscellany, contact me at sharonrkuo@gmail.com. If you enjoyed this, see more projects at my homepage.