API Overview

The smashgg API is not final or considered “published” at this point. The API is subject to change without notice. Please use at your own risk.

API Concepts

In general, objects in our API (e.g. tournaments, brackets, etc.) are accessed like api.smash.gg/objectType/objectId. To make it easier to get data connected to an object, we have a special parameter called expand which is an array field where each value is a string. Different object types have different expand options.

For instance, to get a tournament, with all of its events you would do https://api.smash.gg/tournament/pulsar-premier-league?expand[]=event. If you wanted to also include the phases of the tournament, you would do https://api.smash.gg/tournament/pulsar-premier-league?expand[]=event&expand[]=phase

Objects

Tournaments

Tournaments are kind of self explanatory but they have an important difference in how they're accessed from the API by comparison to other objects. Tournaments are accessed via their slug (which you can get from the tournament's URL). For instance: https://api.smash.gg/tournament/pulsar-premier-league

Expands

  • event - Will return all the events in the tournament
  • phase - Will return all the phases in the tournament
  • groups - Will return all the phase groups in the tournament
  • stations - Will return all the stations/streams in the tournament

Events

Events are always contained in a tournament and represent a game (e.g. Rocket League) and type (e.g. Teams) that a person can enter. If you know an event's ID, you can access it via https://api.smash.gg/event/eventId. If you only know an event’s slug (e.g. melee-singles) and it’s tournament slug (e.g. the-big-house-6), you can access it like https://api.smash.gg/tournament/the-big-house-6/event/melee-singles.

Expands

  • phase - Will return all the phases in the tournament
  • groups - Will return all the phase groups in the tournament

Phases

Phases are containers of brackets. An event can have 0 or more phases. For instance, many tournaments will have a pools phase which has many brackets inside it that progress into a single final bracket phase.

Expands

  • groups - Will return all the phase groups in the phase

Phase Groups

Phase groups are just brackets. They can be of type single elim, double elim, or round robin. Phase groups contain sets. You can access a phase group via: https://api.smash.gg/phase_group/phaseGroupId.

Expands

  • sets - Will return all the sets of the phase group
  • entrants - Will return all the entrants in the phase group
  • standings - Will return standings data if used in conjunction with the seeds expand
  • seeds - Use in conjunction with standings to get standings data. This gives you seeds for the bracket as well.

Example

Phase Group ID’s are typically the last number in a bracket URL.

Sets

Sets are individual matches in a bracket or phase group. Sets have a field for entrant1Id and entrant2Id which are the entrants playing in the set. If either of these is null, this is a bye set.

Set Tasks

Tasks are only applicable for online events. They are the set of things that each entrant must do when playing the set. Some tasks may require actions on behalf of 1 or more participants in the entrant.

Players

Players are a site-wide representation of a person. Players can enter tournaments and when they do a Participant is created for the player and tournament.

Participants

A participant is a representation of a player in a tournament.

Entrant

An entrant is like a container of participants (1 or more) in an event. Entrants are what you'll see displayed in bracket. Entrants have an array of participant IDs that they contain.

Seeds

Seeds are a phase-level concept used for determining where entrants are placed in a bracket within the phase. Seeds have an optional entrantId, an overall

Stations/Streams

Tournament organizers can add stations (e.g. groups of or individual setups at a live event) and streams (e.g. a Twitch stream) to organize matches. To see the stations and streams for a tournament, use the

Stream Queues

Sets (and entire phase groups) can be assigned to streams and then ordered according to their play order. Modifying the play order is currently only supported for streams. To get the list of sets to be played on each stream in the tournament, use the following route: https://api.smash.gg/station_queue/tournamentId where tournamentId can be retrieved from a tournament API hit. This will give you an object with a queues field that has stream ID mapped to an array of set IDs. The data field in the response will have entities for every set and stream in the queue along with event, phase, phase group, entrant, and player data pertaining to the sets in the queue.

Example

Let's say we want to get the top placement in an online teams bracket and know the players of each team who checked in to each match.

First we'll get the events, phases, and phase groups (brackets) for the tournament so we can find out the IDs of each bracket we're interested in: https://api.smash.gg/tournament/pulsar-premier-league?expand[]=phase&expand[]=groups&expand[]=event

Once we have a phase group (bracket) ID that we want placements and check in data for (e.g. 178064), we can do this to get placements and the sets in the bracket: https://api.smash.gg/phase_group/178064?expand[]=sets&expand[]=standings&expand[]=seeds . Access the standings entity to get placements for each entrant.

To get check in information for individual sets within the bracket, get a set ID from the sets entity in the previous API request (e.g. 4761484) and then do https://api.smash.gg/set/4761484?expand[]=setTask . Tasks for a set is contained in the setTask entity. Check in tasks have atype value of 1. Check in data for a task is contained in the metadata field of the task.

Example 2

Goal: Get the current standings of an event and for brackets within the event

Event standings encompass all brackets and phases in the entire event. Bracket standings are just for a single bracket. Bracket standings and event standings are accessed slightly differently.

To get the standings for a single bracket, use https://api.smash.gg/phase_group/323872?expand[]=standings&expand[]=seeds and look at the standings field in the response. There are a few useful fields on each standing item:

  • seedId is the ID of the seed that this standing is for. Look in the seeds response object for more detail about the seed
  • entrantId is the ID of the entrant that the standing is for. Entrants are specific to an event so this can be useful to connect a team or player to other results in the same event.
  • placement is the actual placement in the bracket
  • pendingPlacement is the ordered placement in the bracket by seed number. For instance with 2 out of winners, both entrants may tie in placement at 2, but pendingPlacement would have the top seeded entrant as 1 and the lower seeded entrant as 2.

To get standings for an event, use https://api.smash.gg/tournament/cheeseadelphia-4-1/event/starcraft-ii-legacy-of-the-void-singles/standings?entityType=event&expand[]=entrants&mutations[]=playerData&mutations[]=standingLosses&page=1&per_page=25. Standings are sorted in ascending order to show better-placing entrants first. A few notes about this URL structure:

  • The base structure is /tournament/touranment-slug/event/event-slug/standings so adjust accordingly for your tournament/event
  • Event standings are paginated so you'll want to modify the page parameter to get the full standings for an event


With the above expands and mutations in the URL, you'll get a few extra fields on the standing and entrant objects like losses and player data.

Example 3

Goal: Get match results for a bracket

Using the same expands as before (sets and seeds), we'll use this API endpoint: https://api.smash.gg/phase_group/323872?expand[]=sets&expand[]=seeds

The response will have all the sets for the bracket. Each set has a few useful fields:

  • entrant1Id and entrant2Id which show who was playing in the set
  • entrant1Score and entrant2Score which show the game score of each entrant
  • winnerId and loserId which has the entrantId of the winner and loser for completed sets
  • stationId which shows what station or stream the set was assigned to
  • state which is the status of the match. 1 is unstarted, 6 is called, 2 is started, and 3 is completed.

To get names for each entrant, use the seeds entity in the response. Each seed maps 1-1 with an entrant. Each seed has a mutations field which has some additional info about the objects associated with that seed. For instance, in the response for the above, you can see that the seed has mutations for the participant, player, and entrants. For singles events, entrants and participants are very similar. For teams events, the entrant (the team) is comprised of multiple participants. If you need more detailed info about the participants such as their profile pictures or ranking info, use the players field.

Example 4

Goal: Get all subleagues for a league

To get the ids of all the subleagues in a league, use https://api.smash.gg/tournament/[league-slug]?expand[]=tagsByContainer and look at the “entityContainerTag” field in the response.

These objects are extremely simple and just represent an entity containing another entity (Note that leagues are represented internally as tournaments, so their type will always be “tournament” in any responses):

  • containerType and containerId: the type of the containing entity and its id. For all the entityContainerTags returned by the above request, the containerId should be the same and will be the id of the league that you requested
  • entityType and entityId: the type of the contained entity and its id. If the entityType equals ”tournament”, it is a subleague of the league you requested. It is also possible for the entityType to equal “event”, which is an event directly in the requested league

If you want to get more information about the subleagues than just their ids, you can use https://api.smash.gg/tournament/[league-slug]?expand[]=visibleEntityContainerTag, which returns all the “entityContainerTag”s for the league and its subleagues, as well as the tournaments and events associated with those “entityContainerTag”s.

Example: I want all the subleagues for “brawlhalla-circuit”, so I use https://api.smash.gg/tournament/brawlhalla-circuit?expand[]=tagsByContainer which returns the following:

Now I know that “brawlhalla-circuit” has four subleagues with ids 6755, 6756, 6763, 6762. I can now use https://api.smash.gg/tournament/brawlhalla-circuit?expand[]=visibleEntityContainerTag, and look through the “tournament” array for the objects with those ids to get more information about those subleages.

Example 5

Goal: Get standings for a league

To get the standings for a league, use https://api.smash.gg/standing/[league-slug]/getAllEvents?expand[]=participants&mutations[]=playerData and look at the “standing” array in the response. There are a few useful fields on each standing item:

  • entityType and entityId: this is the type of entity that has the standing (e.g. “player”) and their corresponding id, which can be used to get more information as we’ll discuss below
  • standing: the standing of the entity in the league
  • points: the number of points associated with this standing
  • containerType and containerId: the containerType is the type of entity the standings are for (note that leagues are represented internally as tournaments, so the type for a league will be “tournament”) and the containerId is just the id of that entity, which can be used to get more information about the containing league

It is important to realize that if you are accessing a league that contains subleagues the default behaviour will be to only get the top 3 standings of each subleague. This behaviour can be changed by adding the optional “top” parameter.

Example: Use https://api.smash.gg/standing/brawlhalla-circuit/getAllEvents?expand[]=participants&mutations[]=playerData&top=10 to get the top 10 standings for every subleague.

To get information about the entity (e.g. “player”) associated with a standing, look at the entityType and entityId of the standing and access the matching data objects in the response.

Example: We use https://api.smash.gg/standing/brawlhalla-circuit/getAllEvents?expand[]=participants&mutations[]=playerData&top=10 and pick the first “standing” in the “standing” array, as shown below.

Looking at the “entityType”, we know that this standing is associated with a “player” and we will need to look at the “player” array for more information. We’ll need the “id” of the “player”, which is 11838, since that is the “entityId” of this standing.

We now look at the “player” array in the response and find the object with id 11838 to get all the information about the player (see below).

To get more specific information about the standings of a league, you’ll need the league’s id. To get the ids of subleagues you are interested in see Example 4 above. Once you have the id of the league you are interested in, you can use https://api.smash.gg/standing/tournament/[league-id]/page?expand[]=participants&expand[]=standingPoints&mutations[]=playerData. By default you will get the top 25 standings. This behaviour can be changed by adding the optional “per_page” parameter (e.g. https://api.smash.gg/standing/tournament/[league-id]/page?expand[]=participants&expand[]=standingPoints&mutations=playerData&per_page=50)

The “standing” array will be the same as shown above, but now there will be a “standingPoints” array with the following characteristics:

  • sourceType and sourceId: these fields describe where the points came from, so if the sourceType=”event” and the sourceId=123, the points were awarded from the event with id 123
  • standing: in the case of “event”s, this number represents the placement in that event that awards these points
  • quantity: the number of points this standing is worth

If we ignore special cases, such as when points are awarded directly, and just focus on “standingPoints” where the sourceType=”event”, then we can describe “standingPoints” much more simply: “standingPoints” for an event represent the point structure for that event.

Example: Let’s say I have an event “example-event” with an id of 12345 and I decide that 1st place will get 100 points, 2nd place gets 50 points, 3rd gets 25 points, 4th gets 10 points, and 5th gets 5 points. This would result standing points similar to the following (note that I am leaving out fields irrelevant to this example).

"standingPoints": [

{"id": 123, "sourceType": "event", "sourceId": 12345, "quantity": 100, "standing": 1},

{"id": 124, "sourceType": "event", "sourceId": 12345, "quantity": 50, "standing": 2},

{"id": 125, "sourceType": "event", "sourceId": 12345, "quantity": 25, "standing": 3},

{"id": 126, "sourceType": "event", "sourceId": 12345, "quantity": 10, "standing": 4},

{"id": 127, "sourceType": "event", "sourceId": 12345, "quantity": 5, "standing": 5}

]

It is important to notice that if my event finished with a simple double elimination bracket, two people may get 5th place, but there is only one “standingPoint” entry for 5th. That is because the “standingPoints” just act as a sort of lookup table for what points are associated with what place. If you found the “standing” object for both 5th place entrants in this event, you would see that they both have id 127 in their “pointIds” array.

Example: Let’s say we have determined that the id of the “United States 1v1” subleague of the “Brawlhalla Circuit” is 6755 using the methods described previously. Now we’ll use https://api.smash.gg/standing/tournament/6755/page?expand[]=participants&expand[]=standingPoints&mutations[]=playerData to the following response:

Now we want to find out which events the player with standing 1 has gotten points from, what place he got in that event, and how many points it was worth. So first we’ll take a look at the standing where “standing” equals 1.

We see that this standing is made up of 350 points and because there is only one entry in the “pointIds” array, all 350 points must have come from that one “standingPoints” object. So now we can find the “standingPoints” object with the id 4627.

We can see that the source of these points was the “event” with the id 23910. Now this can be a bit confusing because of the naming, but the field “standing” here means that these points are awarded to the person who placed 1 in that event. Remember that these “standingPoints” just represent the point structure for an event (as discussed in the example above). Finally, if we want to know more about the event, we can use the https://api.smash.gg/event/eventId route. So we use https://api.smash.gg/event/23910 and get the response:

Did this answer your question?