TopDeck.gg API – Tournaments V2 Documentation
Documentation for getting data from TopDeck.gg's Tournaments V2 API
REST API URL: https://topdeck.gg/api
Usage Requirements
Free to Use
The TopDeck.gg API is free to use, providing access to a wealth of data for your projects and applications.
Rate Limits
You are limited to 200 requests per minute. Need a higher limit? E-mail us at [email protected].
Attribution
Any project using the API or data from the API must include proper attribution to TopDeck.gg. This includes a visible credit and a link back to TopDeck.gg.
Example Attribution:
<p>Data provided by <a href="https://topdeck.gg" target="_blank">TopDeck.gg</a></p>
By using the API, you agree to these usage requirements. Thank you for supporting TopDeck.gg!
Required Header
Please acquire an API Key using the link below. All requests must include your API key in the Authorization header.
{
"Authorization": "Your-API-Key"
}
Get API KeyPOST /v2/tournaments
This endpoint retrieves information about completed tournaments. You can retrieve a variety of information, such as players, standings, decklists, matchups, and more. There are powerful filter options available.
Request
Body Parameters
TID: string | array of strings
The ID of the tournament. Can be a single string or an array of strings for multiple tournaments.
game: string
The name of the game for filtering tournaments. Case sensitive. See below.
format: string
The format of the game for filtering tournaments. Case sensitive. See below.
The following games and formats can be filtered. These must be passed to the game
and format
fields. They are case sensitive and must be passed exactly as written below.
Game | Format |
---|---|
Magic: The Gathering |
|
Pokemon |
|
Yu-Gi-Oh |
|
Star Wars Unlimited |
|
Lorcana | Leave format blank ("") |
One Piece | Leave format blank ("") |
Digimon | Leave format blank ("") |
Marvel Snap | Leave format blank ("") |
Shadowverse: Evolve | Leave format blank ("") |
Flesh and Blood | Leave format blank ("") |
Sorcery: Contested Realm | Leave format blank ("") |
Altered | Leave format blank ("") |
start: integer
The Unix timestamp (in seconds) indicating the earliest start date for the tournaments to be included in the response.
end: integer
The Unix timestamp (in seconds) indicating the latest end date for the tournaments to be included in the response.
last: integer
The number of days back from today to include tournaments.
participantMax: integer
The maximum number of participants to include.
participantMin: integer
The minimum number of participants to include.
columns: array of strings
An array specifying which player columns to include in the response. Default: ["decklist", "wins", "draws", "losses"]
[
"name", // Name of the player
"decklist", // URL of the player's decklist
"deckSnapshot", // Object of player's decklist (Magic: The Gathering only)
"commanders", // Array of player's commanders (Magic: The Gathering, EDH only)
"wins", // Total wins by the player
"winsSwiss", // Wins in the Swiss rounds
"winsBracket", // Wins in the Bracket rounds
"winRate", // Overall win rate
"winRateSwiss", // Win rate in the Swiss rounds
"winRateBracket", // Win rate in the Bracket rounds
"byes", // Byes received in the tournament
"draws", // Number of draws
"losses", // Total losses by the player
"lossesSwiss", // Losses in the Swiss rounds
"lossesBracket", // Losses in the Bracket rounds
"id" // Unique player identifier on TopDeck.gg
]
rounds: boolean | array of strings
An array specifying which round details to include in the response. This is default set to false. If set to true, the default is: ["round", "tables"]
[
"round", // The round number or description (e.g., "Top 8")
"tables" // Details about the tables in each round
]
tables: array of strings
An array specifying which table details to include in the response. Default: ["table", "players", "winner", "status"]
[
"table", // The table number
"players", // List of players at the table
"winner", // The winner of the table
"status" // Status of the table (e.g., "Completed")
]
players: array of strings
An array specifying which player details to include in the response. Default: ["name", "id", "decklist"]
[
"name", // Name of the player
"id", // Player ID
"decklist" // URL of the player's decklist
]
Example Request
{
"last": 30,
"columns": ["decklist", "wins", "draws", "losses"],
"rounds": true,
"tables": ["table", "players", "winner"],
"players": ["name", "id", "decklist"],
"game": "Magic: The Gathering",
"format": "EDH",
"participantMax": 100,
"participantMin": 10
}
Response
Success
[
{
"TID": "TournamentID",
"tournamentName": "Tournament Name",
"swissNum": 5,
"startDate": 1627844461,
"topCut": 10,
"standings": [
{
"name": "Player Name",
"id": "Player unique TopDeck.gg Id",
"decklist": "Decklist URL",
"wins": 5,
"winsSwiss": 3,
"winsBracket": 2,
"winRate": 0.83,
"winRateSwiss": 0.75,
"winRateBracket": 1.00,
"draws": 1,
"losses": 2,
"lossesSwiss": 1,
"lossesBracket": 1
},
...
],
"rounds": [
{
"round": 1,
"tables": [
{
"table": 1,
"players": [
{
"name": "Player 1",
"id": "Player1ID",
"decklist": "Decklist URL"
},
{
"name": "Player 2",
"id": "Player2ID",
"decklist": "Decklist URL"
}
],
"winner": "Player 1",
},
...
]
},
...
]
}
]
GET /v2/tournaments/{TID}
This endpoint retrieves detailed information about a specific tournament, including tournament info, standings, and rounds.
Decklists will not appear in the response until the tournament is completed.
Discord Ids will not appear unless the tournament is using them.
Response
Success
{
"data": {
"name": "Tournament Name",
"game": "Game Name",
"format": "Game Format",
"startDate": 1627844461
},
"standings": [
{
"standing": 1,
"name": "Player Name",
"discord": "Discord ID",
"id": "Player ID",
"decklist": "Decklist URL",
"points": 15,
"winRate": 0.8,
"opponentWinRate": 0.6,
"opponentGameWinRate": 0.7,
},
...
],
"rounds": [
{
"round": 1,
"tables": [
{
"table": 1,
"players": [
{
"name": "Player 1",
"discord": "Discord ID",
"id": "Player ID",
"decklist": "Decklist URL"
},
{
"name": "Player 2",
"discord": "Discord ID",
"id": "Player ID",
"decklist": "Decklist URL"
}
],
"winner": "Player 1",
"status": "Completed"
},
...
]
},
...
]
}
GET /v2/tournaments/{TID}/info
This endpoint retrieves detailed information about a specific tournament.
Response
Success
{
"name": "Tournament Name",
"game": "Game Name",
"format": "Game Format",
"startDate": 1627844461
}
GET /v2/tournaments/{TID}/standings
This endpoint retrieves the standings of a specific tournament.
Response
Success
[
{
"standing": 1,
"name": "Player Name",
"discord": "Discord ID",
"id": "Player ID",
"decklist": "Decklist URL",
"points": 15,
"opponentWinRate": 0.7,
"gameWinRate": 0.75,
"opponentGameWinRate": 0.65
}
]
GET /v2/tournaments/{TID}/players/{ID}
This endpoint retrieves information about a specific player in a specific tournament.
Decklists will not appear in the response until the tournament is completed.
Discord Ids will not appear unless the tournament is using them.
Response
Success
{
"name": "Player Name",
"standing": 1,
"decklist": "Decklist URL",
"winRate": 0.83,
"gamesPlayed": 10,
"gamesWon": 8,
"gamesDrawn": 1,
"gamesLost": 1
}
GET /v2/tournaments/{TID}/rounds
This endpoint retrieves all rounds of a specific tournament.
Decklists will not appear in the response until the tournament is completed.
Discord Ids will not appear unless the tournament is using them.
Response
Success
[
{
"round": 1,
"tables": [
{
"table": 1,
"players": [
{
"name": "Player 1",
"discord": "Discord ID",
"id": "Player ID",
"decklist": "Decklist URL"
},
{
"name": "Player 2",
"discord": "Discord ID",
"id": "Player ID",
"decklist": "Decklist URL"
}
],
"winner": "Player 1",
"status": "Completed"
}
]
}
]
GET /v2/tournaments/{TID}/rounds/latest
This endpoint retrieves the latest round of a specific tournament.
Decklists will not appear in the response until the tournament is completed.
Discord Ids will not appear unless the tournament is using them.
Response
Success
[
{
"table": 1,
"players": [
{
"name": "Player 1",
"discord": "Discord ID",
"id": "Player ID",
"decklist": "Decklist URL"
},
{
"name": "Player 2",
"discord": "Discord ID",
"id": "Player ID",
"decklist": "Decklist URL"
}
],
"winner": "Player 1",
"status": "Completed"
}
]
Errors
You may receive the following errors when using the tournaments API.
Bad Request
{
"status": 400,
"error": "Both "game" and "format" fields are required."
}
Invalid API Key
{
"status": 401,
"error": "INVALID API KEY!"
}
Rate limit exceeded
{
"status": 429,
"error": "Rate limit Exceeded"
}
Internal Server Error
If you receive a 500
error, please contact us at [email protected].
{
"status": 500,
"error": "Internal Server Error"
}