Your Privacy Matters

When you click on "Accept All Cookies," you consent to Melee.gg saving cookies on your device. This enables us to enhance your user experience and manage data as outlined in our Cookie Guidelines.

Cookie Preferences

When you browse any section of the website, we may collect or access information through your browser, primarily via cookies. This data may pertain to you, your browsing habits, or your device, and is primarily utilized to ensure that the website functions as you anticipate. While this information generally won't identify you personally, it can help create a more tailored browsing experience for you. We value your privacy and give you the option to opt-out of certain kinds of cookies. Feel free to navigate through the various cookie categories to learn more and adjust your settings. Be aware that opting out of some cookies may affect your experience and the services we can provide.

Essential Cookies

Essential Cookies

These cookies are crucial for the proper operation of the website and can't be deactivated within our system. They typically activate in response to certain actions you undertake, such as setting your privacy options, logging in, or completing forms. These cookies are essential for executing services that you've requested. Opting out of these cookies isn't possible through our settings, but you can configure your browser to block or notify you about them. Be advised that doing so may disrupt some functionalities of the site. These cookies don't collect identifiable personal information.

Analytical Cookies

Analytical Cookies

These cookies help us monitor the website's traffic and performance so that we can fine-tune the Melee.gg experience for you. They let us identify the most and least frequented pages and track user navigation, aiding us in optimizing the site. The data collected is aggregated and remains anonymous. If you decide not to enable these cookies, we won't be able to use your data for performance improvement.

Functional Cookies

Functional Cookies

These cookies add extra features and customizable options to the Melee.gg website, enriching your user experience. They might be set by us or by third-party vendors providing services we've integrated into our site. Should you choose to disable these cookies, some or all of these enhanced functionalities may not operate as intended.


Melee Tournament Data API Documentation

Updated September 12th, 2023
Revision: 3

Melee provides an Application Programming Interface (API) for accessing your tournament data programmatically. The API exposes information available to your organization in a JSON format. To gain access to our API and discuss the fees associated with its use, please email us at contact@melee.gg

Table of Contents


API Details

The API is available at https://melee.gg. API requests are only served over HTTPS. Requests will not be honored over plaintext HTTP. The API uses UTF-8 character encoding for all responses.

Rate Limits and Good Citizenship

We ask that you only fetch data using the API whenever you need it. Constant polling when the tournament is not ongoing or polling too quickly may result in your credentials being revoked.

We encourage you to local cache the data you fetch using the API. A good example would be the tournament details such as phases and rounds, which are unchanging during the course of the tournament.

Submitting excessive requests to the server may result in a HTTP 429 Too Many Requests status code. Continuing to overload the API after this point may result in a temporary or permanent ban of your IP address.

Caching

Endpoints labeled as “cached” use a distributed cache and therefore lag behind up-to-date data. The Time To Live (TTL) on the cache is 5 minutes. Any requests made to this endpoint with an interval less than 5 minutes will return the same data.

Authentication

The Melee API uses Basic access authentication. More information about Basic authentication can be found here: https://en.wikipedia.org/wiki/Basic_access_authentication. The basic authentication header takes a clientId and a clientSecret, which is generated by Melee staff and is located in the user’s settings.

Authentication is per-user and requests using these credentials will have access to tournaments that user has access to on the Melee site.

Use of Melee Data

Melee provides special endpoints to facilitate fetching of tournament information for logistics and broadcast reasons. Sharing of API credentials with third parties without permission of Melee is expressly prohibited. Melee reserves the right to revoke API credentials at any time for failure to comply with its policies. Endpoints labeled as "privileged" require special organizer privileges granted by Melee staff.


Tournament Endpoints

Tournament endpoints are locations for retrieving information about your tournaments, their structure, players, matches, etc.

Each endpoint in this list takes a variable, like {tournamentId}, and return a json object representing that domain.

You may need to use an endpoint to retrieve variables before using other endpoints. For example, if you want to collect all of the matches for a round, you need to use the /Tournament/Tournament endpoint to get the structure of the tournament and then use /Tournament/RoundMatches/ with that round's guid.

Endpoints
  • GET /Tournament/ArchetypeStandings/{tournamentId} cached
  • GET /Tournament/CurrentFeatureMatches/{tournamentId}
  • GET /Tournament/CurrentMatches/{tournamentId}
  • GET /Tournament/CurrentStandings/{tournamentId} cached
  • GET /Tournament/PhaseStandings/{phaseId} cached
  • GET /Tournament/RoundFeatureMatches/{roundId}
  • GET /Tournament/RoundMatches/{roundId}
  • GET /Tournament/Tournament/{tournamentId} cached
  • GET /Tournament/TournamentDecklists/{tournamentId}?format={format} cachedprivileged
  • GET /Tournament/TournamentMatch/{matchGuid}
  • GET /Tournament/TournamentPlayer/{playerId} cached
  • GET /Tournament/TournamentPlayers/{tournamentId} cached
  • GET /Tournament/TournamentWOTCDecklists/{tournamentId}?format={format} cachedprivileged

Tournament

The tournament object contains information about the structure of the tournament. Its main purpose is to communicate round and phase ids for other endpoints.
The Tournament Object

            

Players

The player object represents a player or team in a tournament.

Certain sensitive fields like Age, Region, and WizardsAccountEmail are not populated unless the player has acknowledged that the data is ok to be shared for this tournament during registration. This information is not available to organizers by default.

The player object contains metadata information about the player which can be assigned at registration or via the tournament controller.
The Player Object

            

Matches

Matches are groups of teams that compete in a tournament.

The match object contains metadata information about the players in the match which can be assigned at registration or via the tournament controller.
The Match Object

            

Standings

Standings is a ranked list of players in a tournament.

The standings object contains metadata information about the player which can be assigned at registration or via the tournament controller.
The Standing Object

            

Archetype Standings

Archetype Standings is a ranked list of decklist archetypes for a tournament.
The Archetype Standing Object

            

Player Metadata

Player Metadata is a feature in Melee that allows organizers to upload and associate additional data with their players. This metadata can include custom fields such as name, region, pronouns, or any other information that organizers want to track for each player.

Organizers can easily manage this metadata by manually entering it or importing it from an external source. Once the metadata is associated with the players, it can be accessed and utilized on the tournament controller by staff only.

The Player Metadata feature provides organizers with flexibility and customization options. They can use this data to personalize player information, generate reports, apply custom filters, and sort players based on specific criteria.

Organizers must get permission from each player to share this data with Melee before uploading it to the website.

Uploading Player Metadata

This documentation guide explains how to upload player metadata for a tournament through the Melee.gg website. Following the below steps ensures that you can associate custom metadata with each player effectively.

Requirements
Steps
  1. Export Player Data
    • Log in to the Melee.gg website.
    • Navigate to the tournament controller.
    • Go to the Players tab.
    • Look for the Export button and click on it to export the players' data. A CSV file will be downloaded.
  2. Prepare the CSV File
    • Open the downloaded CSV file using Excel.
    • Delete all columns except for the ID column.
    • The ID column contains unique identifiers for each player, essential for mapping metadata.
  3. Add Metadata Columns
    • Create new columns in Excel for each piece of metadata you wish to associate with the players.
    • For example, if you want to add metadata for player ranks, create a column named Rank.
    • Populate the new metadata columns with data.
    • Be careful to ensure that each piece of metadata is matched correctly with the corresponding player ID. You may use player names for verification.
  4. Save the Modified CSV File
    • Save the Excel sheet as a CSV file.
    • Make sure to select the CSV format from the 'Save as type' dropdown menu.
  5. Upload the Modified CSV File
    • Return to the Players tab on the Melee.gg website.
    • Click on the Upload Player Metadata button.
    • Select the modified CSV file from your computer.
Note: This action will remove all existing metadata and replace it with the data in the uploaded CSV file.

Editing Player Metadata

Steps
  1. Locate the Player
    • Use the search bar or scroll through the list on the players' tab of the tournament controller to find the player whose metadata you wish to edit.
  2. Access Player Details
    • Click on the player's name to access the Player Card popup.
  3. Edit Metadata
    • On the Player Card popup, look for the Player Metadata section.
    • Edit the metadata you wish to change. If the metadata record does not exist, you may need to add it first.
    • Click Save Changes to update the metadata.
  4. Save the Modified CSV File
    • Save the Excel sheet as a CSV file.
    • Make sure to select the CSV format from the 'Save as type' dropdown menu.
  5. Upload the Modified CSV File
    • Return to the Players tab on the Melee.gg website.
    • Click on the Upload Player Metadata button.
    • Select the modified CSV file from your computer.

Data Replacement in the Melee API

Tournament broadcasts can utilize our API's data replacement feature. Simply upload a modified CSV file with additional player metadata, and our system will seamlessly incorporate this data into the Melee API responses.

What You Need to Know

If you're looking up tournament results, player rankings, or any other details through the Melee API, the system checks for any extra metadata you've uploaded. If present, this data will be automatically included in the API responses.

How It Works

  1. Use the tournament controller to upload a CSV file that contains additional player information, such as 'Rank' or 'Nickname'.
  2. Our system automatically matches this added information with players based on their unique IDs.
  3. When tournament staff requests player data, the API response will include the additional metadata you've uploaded.

Why It's Useful

This feature enhances the depth of player statistics, enriches tournament broadcasts, and provides extra context for post-tournament reports.

Need Help?

For any questions or issues, don't hesitate to contact our support team.