API Frequently Asked Questions

How do limits and offsets work?

When querying on a list of resources, you are able to specify two parameters that help you with pagination - limit and offset. Limit and offset work together in the following way:

  • The objects are first filtered and sorted according to any other parameters.
  • The starting index of the objects in the list that are returned is specified by the 'offset' parameter.
  • The number of objects returned per page of objects is specified by the 'limit' parameter.

To give an example, if you want to fetch 15 objects per page, but start at the 60th object, limit is 15 and offset is 60.

What are the gender choices?

The types of genders you can choose from are 'open', 'mixed', 'womens', and 'mens'

Each league must specify which gender plays in the league. If an organization such as the Madison Ultimate Frisbee Association (MUFA) caters to different gender groupings, that organization may have several leagues. For instance, MUFA would have leagues such as "MUFA Fall League Mixed M/W", "MUFA Fall League Mixed T/R", "MUFA Spring League Men's M/W", "MUFA Spring League Women's", "MUFA Summer League Rec A Mixed T/R", etc.

What are the sport choices?

The types of sports you can choose from are: 'ultimate', 'goaltimate', 'soccer', 'basketball', 'baseball', 'football', 'tennis', 'cricket', 'rugby', 'field hockey', 'volleyball', 'table tennis', 'softball', 'flag football', 'lacrosse', 'broomball', 'water polo', 'handball', 'ice hockey', 'dodgeball', 'kickball', and 'foosball'.

If you would like to see another sport added, leave a note on our Community Page and feel free to tell others behind your cause to go to the page to support the idea. If it has enough support, we will add your sport next.

How do I format a time using ISO Format?

Our API reads ISO 8601 formatted times. This format looks like YYYY-MM-DDTHH:MM:SS-hh:mm where each part is defined as follows:

  • YYYY-MM-DD - The date, denoted by the year, month, and day. For example, 2012-02-08 represents Feb 8th, 2012
  • T - The letter 'T' is a separator that is placed between the date and the time. You don't need to touch this.
  • HH:MM:SS - The time using the 24-hour notation including seconds. For example, 14:12:00 represents 2:12pm.
  • ±hh:mm - The timezone offset from UTC. You can find codes here. This can start with a + or a -. For example, -06:00 represents Central Standard Time

How do I denote a timezone?

Timezones are specified by their human readable Olson Timezone names. They are specified by the TZ column in the Wikipedia list of Timezone Names. Several other common timezone names are available as well, including "US/Eastern", "US/Central", "US/Mountain", "US/Pacific", and "UTC".

How are teams joined across seasons?

Each Team entity belongs to exactly one season, and Teams can be "joined" across multiple seasons. For instance, the Team named Sub Zero played in the USAU Club Open 2010 season as well as the USAU Club Open 2011 season, so there will be two separate resource entities for Sub Zero with seaparate ids. Each Sub Zero entity can have different rosters, belong to different tournaments, and optionally even have different names.

The two Team entities are linked by the 'related_team_ids' field. It is important to specify related teams so a consumer looking at a team in one season can discover the resources for the Team's other seasons.

Possible Gotchas

When creating or updating a Team entity, any 'related_team_ids' you specify will be related to the Team entity along with any teams already related to those 'related_team_ids'. Thus, if you specify [12] for 'related_team_ids' but the team with id 12 is already related to [13,14,15], your Team entity will be related to [12,13,14,15].

When updating a Team entity, if you do not specify the 'related_team_ids' field or enter [] into the field, then all existing 'related_team_ids' will be removed.

All related teams must reside in different seasons from one another and the Team entity.

What HTML is allowed?

Some string fields specify that some HTML is allowed. HTML tags are simply an option, but are not required. The tags that are allowed are <p>, <h2>, <h3>, <h4>, <b>, <strong>, <i>, <ul>, <ol>, <span>, <li>, <a>, and <em>.

How are teams in a pool ranked?

The "Rank" column in a pool is computed as follows. All teams in each pool are ranked by the number of wins and ties, where 3 ties are worth 1 win. If teams are tied, break that tie using the ranking criteria below. Each ranking criterion is used to rank all of the tied teams, not just to determine the highest ranked team. If, after the application of a ranking criterion, all of the teams remain tied, go to the next criterion. If not all teams remain tied, but one or more subgroups of the teams remain tied, separate these subgroups from the ranking. Each subgroup is then to be ranked separately, starting with the first ranking criterion.

  1. Number of games won and tied (where 3 ties are worth 1 win), counting only games between the teams that are tied.
  2. Point difference, counting only games between the teams that are tied.
  3. Point difference, counting games against all common opponents.
  4. Points scored per game, counting only games between the teams that are tied.
  5. Points scored per game, counting games against all common opponents.

This way of ranking teams is compatible with the WFDF Rules of Ultimate 2013.

What are the different scheduling formats?

Leaguevine has two different scheduling formats that you can choose from named "Regular" and "Swiss".

The Regular format allows you to create pools and brackets for your tournament. Tournaments default to this if no option is specified.

The Swiss format allows you to create swiss rounds and use our dynamic swiss scheduler to create rounds on the fly as your tournament progresses. You can also add brackets to Swiss format tournaments. Swiss format tournaments are quite different from tournaments that use pools because teams do not know who they will play in their next game until their current game is over. The advantage of this style is that it aims to create more even matchups as the tournament progresses. To get an idea of how a swiss tournament will work in practice, take a look at our blog entry on Wisconsin Swiss.

How do brackets work?

To create a bracket through the Leaguevine API, you need to specify the number of rounds. Our brackets are limited to between 1 and 4 rounds because that is how many can fit nicely on our tournament bracket page. 1 round means you want to create a single game, 2 rounds means a 4 team bracket, 3 rounds means an 8 team bracket and 4 rounds means a 16 team bracket.

Each of these rounds is numbered. Round 0 is the finals, round 1 is the semifinals, round 2 is the quarterfinals, and round 3 is the round of 16.

After you create the full bracket, you may remove games as you see fit. For instance, if you have a 12 team bracket where 4 teams get first round byes, you would create a 4 round bracket and then remove the appropriate 4 games.

At this time, you cannot add more games to brackets to construct arbitrarily shaped brackets. You may, however, connect winners and losers of brackets to other brackets which will essentially give you the same behavior. You can connect winners and losers by modifying the next_game_for_winner_id and next_game_for_loser_id attributes of the bracket games.

What types of Swiss Scoring can I use?

Leaguevine has three types of Swiss Scoring systems that you can choose from named "Regular", "Victory Points" or "Power Ranking". Tournaments default to Regular if this is not specified.

Scoring systems determine how teams are ranked. Each team is given a numerical value at the conclusion of every round, even if they had a bye. Thus, the difference between the scoring systems is that they will award teams different amounts of points for victories/losses/byes.


The Regular format gives the winner 1 point, the loser 0 points, and a team that has a bye 1 point. The number of points awarded to a team that has a bye is configurable.

Victory Points

The Victory Points format was created by the folks at the Windmill Windup and rewards teams based on point differential in games. Here is the table of victory points awarded if the games go up to 13 points:

Swiss Point Allocation
Margin of Victory Swiss Points for Winner Swiss Points for Loser

Power Ranking

Power rankings assign a number to every team representing its strength (or power) with the intention that the point difference in a game equals the difference in strength of the participating teams. After each round, the computer calculates the team strengths that best fit the results of all games played so far.

For example, if Team Alice wins against Team Bob with a score of 15-10, this result can be explained by assigning a strength of +2.5 to Team Alice and a strength of -2.5 to Team Bob. (Of course, any two numbers with a difference of +5 would work, but let us try to keep the numbers as small as possible in absolute value.) If there are more teams with many games played among them, it becomes more difficult to assign strengths to the teams, but we use computer methods to optimize these numbers so that they fit the outcomes as well as possible.

A possible interpretation of these numbers is the following: If Team Charlie with strength +3 plays Team Eve with strength -2, Team Charlie is expected to win with a point difference of +5. In principle, Team Charlie will improve its strength by winning with an even higher margin, Team Eve will improve its strength by losing with less than 5 points difference. In practice, the change in strength after a round also depends on the performance of the previous opponents of Team Charlie and Team Eve (as well as the opponents of the opponents etc.).

What are the Swiss Pairing Types?

Leaguevine has three types of swiss pairing that you can choose from named "Adjacent Pairing", "Fold Pairing", and "Slide Pairing". Tournaments default to "Adjacent Pairing" if this is not specified.

At the end of every round, teams are ranked based on their record. Teams with the same record are then further ranked based on tie breakers specified in the Swiss Scoring systems section. Once teams are ranked, matchups need to generated and to decide who plays who, a certain pairing type is used. If there are 8 teams with the ranks 1, 2, 3, 4, 5, 6, 7, and 8 the three different pairing algorithms will create the following pairings.

Adjacent Pairing: 1 vs 2, 3 vs 4, 5 vs 6, 7 vs 8

Fold Pairing: 1 vs 8, 2 vs 7, 3 vs 6, 4 vs 5

Slide Pairing: 1 vs 5, 2 vs 6, 3 vs 7, 4 vs 8

What are the 'live' and 'hidden' visibilities?

Every object is marked as either 'live' or 'hidden'. Live objects are visible to absolutely anyone. Hidden objects are visible only to the owner, and to any other people the owner has granted permissions to (for instance, hidden tournaments and tournament related objects can be viewed by other tournament admins for that tournament).

The idea behind hidden objects is to give users a chance to create something but not publish it until it is ready for the world to see.

How does the Events Resource work?

Each event type corresponds to a different in-game action. Please see our full events specification for event types.

What is a GroupMe Bot ID?

GroupMe is a (free) messaging service (owned by Skype/Microsoft) for various mobile-phone platforms. It has a well-documented API. This tutorial explains how to create message bots. Each bot comes with an ID that can be added to a team using the "GroupMe Bot ID" field. Once a GroupMe Bot ID is registered, team notifications will be automatically posted from Leaguevine to this bot. In Swissdraw tournaments, teams will be notified about the following events:

  • A new round has been made live. A team is informed about their current standing and their upcoming opponent, as well as the starting time and field of the next match.
  • A final game score has been submitted.
  • A sportmanship score has been submitted (either by the team or by the opponent).