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
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.
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.
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.
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.
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 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.
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.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.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.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.
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.
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.
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.
This feature enhances the depth of player statistics, enriches tournament broadcasts, and provides extra context for post-tournament reports.
For any questions or issues, don't hesitate to contact our support team.