API Documentation
The e-Sports Earnings API allows you to access up-to-date information from the site in a format you can use in your applications. Because the API is still in beta, functionality will be limited in order to focus on testing service quality. As development of the API continues, this documentation will expand and be organized into multiple pages.
Obtaining an API Key
Usage of the API requires the use of an API Key. You can acquire one by registering in the Development Area. Use of the APIs also requires that you agree to the Development Area Terms of Use.
Your API Key can be found on the "API Stats" page in the Development Area.
Output Formats
All API calls take on the following format:
http://api.esportsearnings.com/v<versionnumber>/<methodname>?apikey=<apikey>&format=<format>.
Version Number corresponds to the version of the API being used. Because the API is currently in beta, the current version number is 0.
Method Name is the function of the API which will be called. (see below)
Format can be any of:
- json - Output is returned in JSON format.
- xml - Output is returned as an XML document.
- csv - Output is returned as a CSV file.
Handling Errors
All requests to the API should check if HTTP Code 200 has been returned before doing anything else. If not, no API data has been sent. After confirming HTTP Code 200, should an error occur in an API request, an Error Code will be returned in the specified format.
For example, an API call returns the following message in JSON format:
{"ErrorCode":1002}
This indicates that the database is too busy to process the request. Your application should check if "ErrorCode" has been returned, since this will always be the output in the event of an error regardless of the method called. The full list of error codes is listed below.
- 1000 - Unknown Error
- 1001 - Database Error
- 1002 - Database Busy
- 1009 - Unknown Method Name (misspelled in request?)
- 1010 - Invalid API Key
- 1011 - Access Denied (Too Frequently)
- 1012 - Access Denied (API Key Restricted)
Determining Unique IDs
Every record on the website, such as players, games, teams, etc., all have their own unique ID that can be found in their URL. For example:
http://www.esportsearnings.com/players/1490-f0rest-patrik-lindberg
The playerid is 1490.
Restrictions of the API
In order to ensure continued access and fast load times to information on the site, restrictions on the API will be placed. You may only access the API at most once per second. Please store any information retrieved from the API locally, and refresh the information every once in a while.
API Function Calls
The following methods are currently available in the API:
LookupPlayerById
LookupPlayerById returns earnings for a single player.
Usage:
http://api.esportsearnings.com/v0/LookupPlayerById?apikey=<apikey>&playerid=<playerid>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- playerid - The unique ID associated with the player on the website.
Output:
- NameFirst - Player's first name.
- NameLast - Player's last name.
- CurrentHandle - Player's currently used in-game handle or ID.
- CountryCode - Two-letter country code based on the ISO 3166-1 alpha-2 standard.
- WorldRanking - Worldwide prize money ranking.
- CountryRanking - Country-specific prize money ranking determined by the player's country code.
- TotalUSDPrize - Total prize money won by the player in US Dollars.
- TotalTournaments - Number of tournaments the player has recorded results in.
LookupPlayerTournaments
LookupPlayerTournaments returns a list of 100 tournament results for a single player, sorted by date.
Usage:
http://api.esportsearnings.com/v0/LookupPlayerTournaments?apikey=<apikey>&playerid=<playerid>&offset=<offset>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- playerid - The unique ID associated with the player on the website.
- offset - The number of tournaments to skip before returning results. (default: 0)
Output:
- RankText - Text associated with the player's placement in the tournament.
- Prize - Raw value of the prize money issued in its original currency.
- ExchangeRate - Exchange Rate to US Dollars on the date the tournament ended. Used to calculate value of prize money in USD.
- CurrencyCode - Three-letter currency code based on the ISO 4217 standard.
- TournamentName - Short-hand name of the tournament. (or full name if it's short enough)
- EndDate - Date the tournament ended.
- GameId - Unique identification number associated with a game on the site.
- Note - Additional notes describing the curcumstances of the tournament result.
- TeamPlayers - Number of players on the team, if applicable. Used to divide the prize money in earning calculations.
LookupHighestEarningPlayers
LookupHighestEarningPlayers returns a list of 100 players with the highest overall prize money won.
Usage:
http://api.esportsearnings.com/v0/LookupHighestEarningPlayers?apikey=<apikey>&offset=<offset>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- offset - The number of players to skip before returning results. (default: 0)
Output:
- PlayerId - Unique identification number associated with a player on the site.
- NameFirst - Player's first name.
- NameLast - Player's last name.
- CurrentHandle - Player's currently used in-game handle or ID.
- CountryCode - Two-letter country code based on the ISO 3166-1 alpha-2 standard.
- TotalUSDPrize - Total prize money won by the player in US Dollars.
LookupGameById
LookupGameById returns the prize money for a single game.
Usage:
http://api.esportsearnings.com/v0/LookupGameById?apikey=<apikey>&gameid=<gameid>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- gameid - The unique ID associated with the game on the website.
Output:
- GameName - Name of the game.
- TotalUSDPrize - Total prize money awarded for the game in US Dollars.
- TotalTournaments - Number of recorded tournaments for the game.
- TotalPlayers - Number of players with records in the game.
LookupHighestEarningPlayersByGame
LookupHighestEarningPlayersByGame returns a list of 100 players with the highest overall prize money won.
Usage:
http://api.esportsearnings.com/v0/LookupHighestEarningPlayersByGame?apikey=<apikey>&gameid=<gameid>>&offset=<offset>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- gameid - The unique ID associated with the game on the website.
- offset - The number of players to skip before returning results. (default: 0)
Output:
- PlayerId - Unique identification number associated with a player on the site.
- NameFirst - Player's first name.
- NameLast - Player's last name.
- CurrentHandle - Player's currently used in-game handle or ID.
- CountryCode - Two-letter country code based on the ISO 3166-1 alpha-2 standard.
- TotalUSDPrize - Total prize money won by the player in US Dollars.
LookupRecentTournaments
LookupRecentTournaments returns a list of the latest 100 tournaments that ended chronologically.
Usage:
http://api.esportsearnings.com/v0/LookupRecentTournaments?apikey=<apikey>&offset=<offset>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- offset - The number of players to skip before returning results. (default: 0)
Output:
- TournamentId - Unique identification number associated with a tournament on the site.
- GameId - Unique identification number associated with a game on the site.
- TournamentName - TournamentName - Short-hand name of the tournament. (or full name if it's short enough)
- StartDate - Date the tournament started.
- EndDate - Date the tournament ended.
- Location - Town or city that the event took place (or "online" if it was held online).
- Teamplay - Boolean determining whether the tournament was held between individuals (1v1, FFA) or teams (2v2, 3v3, 4v4, 5v5, etc.).
- TotalUSDPrize - Total prize money awarded in the tournament in US Dollars.
Notes:
- If "Teamplay" is false, use "LookupTournamentResultsByTournamentId" to retrieve results.
- If "Teamplay" is true, use "LookupTournamentTeamResultsByTournamentId" to retrieve results, and "LookupTournamentTeamPlayersByTournamentId" to retrieve players.
LookupTournamentById
LookupTournamentById returns the prize money and other information for a single tournament.
Usage:
http://api.esportsearnings.com/v0/LookupTournamentById?apikey=<apikey>&tournamentid=<tournamentid>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- tournamentid - The unique ID associated with the tournament on the website.
Output:
- GameId - Unique identification number associated with a game on the site.
- TournamentName - TournamentName - Short-hand name of the tournament. (or full name if it's short enough)
- StartDate - Date the tournament started.
- EndDate - Date the tournament ended.
- Location - Town or city that the event took place (or "online" if it was held online).
- Teamplay - Boolean determining whether the tournament was held between individuals (1v1, FFA) or teams (2v2, 5v5, etc.).
- TotalUSDPrize - Total prize money awarded in the tournament in US Dollars.
Notes:
- If "Teamplay" is false, use "LookupTournamentResultsByTournamentId" to retrieve results.
- If "Teamplay" is true, use "LookupTournamentTeamResultsByTournamentId" to retrieve results, and "LookupTournamentTeamPlayersByTournamentId" to retrieve players for those results.
- Individual-based tournaments and team-based tournaments have two completely different methods of accounting for unknown players. See the notes of those methods for more information.
LookupTournamentResultsByTournamentId
LookupTournamentResultsByTournamentId returns a list of tournament placements for tournaments held between individuals (1v1, FFA). Use this method if "Teamplay" is set to false.
Usage:
http://api.esportsearnings.com/v0/LookupTournamentResultsByTournamentId?apikey=<apikey>&tournamentid=<tournamentid>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- tournamentid - The unique ID associated with the tournament on the website.
Output:
- Ranking - Number that determines ordering on the list. Ranks 1, 2 and 3 are also used to show a gold, silver and bronze background respectively.
- RankText - Formatted text associated with the player's placement in the tournament.
- TeamId - Unique identification number associated with a team on the site.
- TeamName - Name of the player's associated team.
- PlayerId - Unique identification number associated with a player on the site.
- CountryCode - Two-letter country code based on the ISO 3166-1 alpha-2 standard.
- NameFirst - Player's first name.
- NameLast - Player's last name.
- CurrentHandle - Player's currently used in-game handle or ID.
- ShowLastNameFirst - Boolean determining whether or not the last name should be displayed before the first name.
- PrizeUSD - Prize money awarded to the player in US Dollars.
Notes:
- For v0 of the API, "TeamId" and "TeamName" may not work as intended. The site currently has an unreliable method of determining team associations from individual and team earnings. This will be rectified in v1.
- If a placement is associated with an unknown player, the "CurrentHandle" will be "##UNKNOWN##". "PlayerId" in this instance is only used to return a unique row for each unknown player and can be discarded.
LookupTournamentTeamResultsByTournamentId
LookupTournamentTeamResultsByTournamentId returns a list of tournament placements for tournaments held between teams (2v2, 5v5, etc.). Use this method if "Teamplay" is set to true.
Usage:
http://api.esportsearnings.com/v0/LookupTournamentTeamResultsByTournamentId?apikey=<apikey>&tournamentid=<tournamentid>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- tournamentid - The unique ID associated with the tournament on the website.
Output:
- Ranking - Number that determines ordering on the list. Ranks 1, 2 and 3 are also used to show a gold, silver and bronze background respectively.
- RankText - Formatted text associated with the player's placement in the tournament.
- TeamId - Unique identification number associated with a team on the site.
- TeamName - Name of the player's associated team.
- TournamentTeamId - Unique identification number associated with a team earning on the site. Not to be confused with "TeamId".
- TournamentTeamName - Name of the team associated with the team placement.
- PrizeUSD - Prize money awarded to the team in US Dollars. Divide this value by the number of players + UnknownPlayerCount to get the prize per player.
- UnknownPlayerCount - Number of unknown players on the team. Used if the full roster of the team is not known to correct division with PrizeUSD.
Notes:
- For v0 of the API, "TeamId" and "TeamName" may not work as intended. The site currently has an unreliable method of determining team associations for individual and team earnings. This will be rectified in v1.
- "TournamentTeamId" refers to a team earning for a single tournament, while "TeamId" refers to a team record on the site.
- "TournamentTeamName" is the name of the team specifically for the associated tournament. It may include the title sponsor where appropriate (Fnatic.MSI for Fnatic), or may not be associated with a team at all, such as an all-stars match or two players pairing up for a 2v2 tournament.
- The "LookupTournamentTeamResultsByTournamentId" method should be called along with "LookupTournamentTeamPlayersByTournamentId". Use "TournamentTeamId" to associate players with their respective team earning.
- Formula for calculating prize money for each player: PrizeUSD / (Number of known players + UnknownPlayerCount)
- Number of known players retrieved from the "LookupTournamentTeamPlayersByTournamentId" method may be zero for some tournaments, and "UnknownPlayerCount" is usually zero. Ensure that you are not dividing by zero!
LookupTournamentTeamPlayersByTournamentId
LookupTournamentTeamPlayersByTournamentId returns a list of players associated with the "tournament teams" of a tournament. Use this method if "Teamplay" is set to true.
Usage:
http://api.esportsearnings.com/v0/LookupTournamentTeamPlayersByTournamentId?apikey=<apikey>&tournamentid=<tournamentid>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- tournamentid - The unique ID associated with the tournament on the website.
Output:
- TournamentTeamId - Unique identification number associated with a team earning on the site. Used to group players with their associated team earning.
- PlayerId - Unique identification number associated with a player on the site.
- CountryCode - Two-letter country code based on the ISO 3166-1 alpha-2 standard.
- NameFirst - Player's first name.
- NameLast - Player's last name.
- CurrentHandle - Player's currently used in-game handle or ID.
- ShowLastNameFirst - Boolean determining whether or not the last name should be displayed before the first name.
Notes:
- The "LookupTournamentTeamPlayersByTournamentId" method should be called along with "LookupTournamentTeamResultsByTournamentId". Use "TournamentTeamId" to associate players with their respective team earning.
- Some team-based tournaments will return team earnings, but not players for those team earnings. This is because information on player rosters for those tournaments have not been added yet.
LookupHighestEarningTeams
LookupHighestEarningTeams returns a list of 100 teams with the highest overall prize money won.
Usage:
http://api.esportsearnings.com/v0/LookupHighestEarningTeams?apikey=<apikey>&offset=<offset>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- offset - The number of teams to skip before returning results. (default: 0)
Output:
- TeamId - Unique identification number associated with a team on the site.
- TeamName - Name of the team.
- TotalUSDPrize - Total prize won by the team in US Dollars.
- TotalTournaments - Total number of tournaments that a team received prize money in.
LookupHighestEarningTeamsByGame
LookupHighestEarningTeamsByGame returns a list of 100 teams with the highest prize money won for a specific game.
Usage:
http://api.esportsearnings.com/v0/LookupHighestEarningTeamsByGame?apikey=<apikey>&gameid=<gameid>&offset=<offset>
Parameters:
- apikey - The unique API Key associated with your account.
- format - Format of the output. (default: JSON)
- gameid - The unique ID associated with the game on the website.
- offset - The number of teams to skip before returning results. (default: 0)
Output:
- TeamId - Unique identification number associated with a team on the site.
- TeamName - Name of the team.
- TotalUSDPrize - Total prize won by the team for the game in US Dollars.
- TotalTournaments - Total number of tournaments for the game that a team received prize money in.