Tournia API

API v2 Introduction

Welcome to the Tournia API documentation.

The Tournia API allows you to manage all the tournament functionality in a simple, programmatic way using conventional HTTP requests. The API is based on conventional REST principles.

All of the functionality that you are familiar with in the Tournia match control panel is also available through the API, allowing you to script the complex actions that your situation requires.

The API documentation will start with a general overview about the design and technology that has been implemented, followed by reference information about specific endpoints.

Code example

# You can already try out a request.
# The url contains the tournament url, which can be set in the tournament settings.
# For now, you can use the test tournament, which is open to everyone.

https://www.tournia.net/api/v2/test/tournament
Put in the header X-API-token: TESTTESTTESTTESTTEST

# If everything goes well, you should see some information about the tournament.

Requests

Any tool that is fluent in HTTP can communicate with the API simply by requesting the correct URI. Requests should be made using the HTTPS protocol so that traffic is encrypted. The interface responds to different methods depending on the action required.

Requests

GET

For simple retrieval of information about your tournament, players, etc., you should use the GET method. The information you request will be returned to you as a JSON object.

Any request using the GET method is read-only and will not affect any of the objects you are querying.

DELETE

To destroy a resource and remove it from your tournament, the DELETE method should be used. This will remove the specified object if it is found. If it is not found, the operation will return a response indicating that the object was not found.

This idempotency means that you do not have to check for a resource's availability prior to issuing a delete command, the final state will be the same regardless of its existence.

PUT

To update the information about a resource in your account, the PUT method is available.

Like the DELETE Method, the PUT method is idempotent. It sets the state of the target using the provided values, regardless of their current values. Requests using the PUT method do not need to check the current attributes of the object.

POST

To create a new object, your request should specify the POST method.

The POST request includes all of the attributes necessary to create a new object. When you wish to create a new object, send a POST request to the target endpoint.

Code example

GET https://www.tournia.net/api/v2/test/locations will return a list with all locations.

GET https://www.tournia.net/api/v2/test/locations/15 will return information about the location with ID 15.

POST https://www.tournia.net/api/v2/test/locations will create a new location.

PUT https://www.tournia.net/api/v2/test/locations/15 will edit the location with ID 15.

DELETE https://www.tournia.net/api/v2/test/locations/15 will remove the location with ID 15.

HTTP Statuses

Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.

In the event of a problem, the status will contain the error code, while the body of the response will usually contain additional information about the problem that was encountered.

In general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered.

Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed.

If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.

Example error response
HTTP/1.1 403 Forbidden
{
	"id":       "forbidden",
	"message":  "You do not have access, have you set X-API-KEY in the header?"
}

Meta

In addition to the main resource root, the response may also contain a meta object. This object contains information about the response itself.

The meta object can contains a total key that is set to the total number of objects returned by the request.

The meta object will only be displayed when it has a value.

Sample Meta object
{
	. . .
	"meta": {
		"total": 43
	},
	"players": [
		{
			"name": "Player 1",
			. . .
		}
	]
	. . .
}

Authentication

There are three ways to authenticate for a web request:

  1. X-API-KEY in headers: the best way for you is to put the API key in the header. This can be done by sending X-API-KEY: YOUR_KEY_VALUE in the headers (of course replacing your YOUR_KEY_VALUE).
  2. Logging in and sending the cookie: this is the way the Tournia website works. You login on tournia.net, and using a cookie your authentication is checked.
  3. Oauth: currently in beta. If you are interested in using Oauth, contact us.

Generate an API key by going to the API section of the control panel. Use an existing key if you have saved one, or generate a new key with the "Create new API key" button.

 

Parameters

There are two different ways to pass parameters in a request with the API.

When passing parameters to filter a response on GET requests, parameters can be passed using standard query attributes. In this case, the parameters would be embedded into the URI itself by appending a ? to the end of the URI and then setting each attribute with an equal sign. Attributes can be separated with a &.

When passing parameters to create (POST) or update (PUT) an object, there are two ways:

  • Parameters should preferably be passed as a JSON object containing the appropriate attribute names and values as key-value pairs. When you use this format, you should specify that you are sending a JSON object in the header. This is done by setting the Content-Type header to application/json. This ensures that your request is interpreted correctly.
  • Parameters can be submitted with x-www-form-urlencoded. Make sure that there is no Content-Type set in the headers.

By default the response will be in JSON. You can also request a XML response by defining Content-Type in the header with application/xml. The POST and PUT data in the body should in that case also be XML.

cURL example in terminal
	
export API_KEY=TESTTESTTESTTESTTEST
	
Pass filter parameters as a query string
	curl -H "X-API-KEY: $APIKEY" \
	-X GET \
	"https://www.tournia.net/api/v2/test/messages?page=2"
	
Pass parameters as a JSON object
	curl -H "X-API-KEY: $APIKEY" \
	-H "Content-Type: application/json" \
	-d '{"name": "Pool name", "nrPlayersInTeam": "2"}' \
	-X POST "https://www.tournia.net/api/v2/test/pools"
	

Cross Origin Resource Sharing

In order to make requests to the API from other domains, the API implements Cross Origin Resource Sharing (CORS) support.

CORS support is generally used to create AJAX requests outside of the domain that the request originated from. This is necessary to implement projects utilizing the API. This tells the browser that it can send requests to an outside domain.

The procedure that the browser initiates in order to perform these actions (other than GET requests) begins by sending a "preflight" request. This sets the Origin header and uses the OPTIONS method. The server will reply back with the methods it allows and some of the limits it imposes. The client then sends the actual request if it falls within the allowed constraints.

This process is usually done in the background by the browser, and you don't have to worry about it. You can manually emulate this process using the example provided. The headers that will be set to show the constraints are:

  • Access-Control-Allow-Origin: This is the domain that is sent by the client or browser as the origin of the request. It can set through an Origin header.
  • Access-Control-Allow-Methods: This specifies the allowed options for requests from that domain. This will generally be all available methods.
  • Access-Control-Allow-Headers: This will contain the headers that will be available to requests from the origin domain.
You should not need to be concerned with the details of these headers, because the browser will typically do all of the work for you.

Example preflight reequest
curl -I -H "Origin: https://example.com" -X OPTIONS "https://www.tournia.net/api/v2/test/tournament"

Example preflight response
. . .
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
. . .

Tournament

With the Tournament entity you can get information about the tournament. In specific it is also possible to request the possible status options for registrations, and the unique registration options used for all current registrations.

Most values are self-explanatory, but some values will be explained in a bit more detail.

Tournament Object

name
string Name of the tournament.
startDateTime
DateTime Start of the tournament, including timezone information.
endDateTime
DateTime End of the tournament, including timezone information.
dateText
String Written date for startDateTime to endDateTime
registrationOpenDateTime
DateTime When registrations open for public, including timezone information.
registrationClosedDateTime
DateTime When registrations close for public, including timezone information.
pageHtml
String HTML of first page of the tournament
Tournament example

https://www.tournia.net/api/v2/test/tournament
Header X-API-token: TESTTESTTESTTESTTEST

# Response Object
{
  "tournamentId": 4,
  "url": "test",
  "name": "Test Tournament",
  "startDateTime": {
    "timezone": {
      "name": "Europe/Amsterdam",
      "location": {
        "country_code": "NL",
        "latitude": 52.36667,
        "longitude": 4.9,
        "comments": ""
      }
    },
    "offset": 3600,
    "timestamp": 1449010800
  },
  "endDateTime": {
    "timezone": {
      "name": "Europe/Amsterdam",
      "location": {
        "country_code": "NL",
        "latitude": 52.36667,
        "longitude": 4.9,
        "comments": ""
      }
    },
    "offset": 3600,
    "timestamp": 1449097200
  },
  "dateText": "Wednesday 2 December 2015 - Thursday 3 December 2015",
  "registrationOpenDateTime": {
    "timezone": {
      "name": "Europe/Amsterdam",
      "location": {
        "country_code": "NL",
        "latitude": 52.36667,
        "longitude": 4.9,
        "comments": ""
      }
    },
    "offset": 3600,
    "timestamp": 1446332400
  },
  "registrationClosedDateTime": {
    "timezone": {
      "name": "Europe/Amsterdam",
      "location": {
        "country_code": "NL",
        "latitude": 52.36667,
        "longitude": 4.9,
        "comments": ""
      }
    },
    "offset": 3600,
    "timestamp": 1451602740
  },
  "pageHtml": "

Lorem Ipsum

", "isLiveScoreAllowed": true, "isLive2ndCallAllowed": true, "nrSets": 3, "checkScoreMin": null, "checkScoreMax": null }

Player

Players register themselves for the tournament. This doesn't immediately mean they play in the tournament as well; some are spectators, some cancel their registration or don't show up.

Player Object

name
string Name of the tournament.
startDateTime
DateTime Start of the tournament, including timezone information.
endDateTime
DateTime End of the tournament, including timezone information.
dateText
String Written date for startDateTime to endDateTime
registrationOpenDateTime
DateTime When registrations open for public, including timezone information.
registrationClosedDateTime
DateTime When registrations close for public, including timezone information.
pageHtml
String HTML of first page of the tournament
Player example

https://www.tournia.net/api/v2/test/players/PLAYER_ID

# Response Object
{
  "playerId": 152,
  "firstName": "Test",
  "lastName": "Player 1",
  "fullName": "Test Player 1",
  "registrationDate": "18-May-2013 23:56:49",
  "status": "Registered",
  "ready": false,
  "nonreadyReason": null,
  "gender": "Male",
  "disciplines": {
    "Singles": {
      "disciplineId": 105,
      "disciplineName": "Men Singles A",
      "partner": null
    },
    "Doubles": {
      "disciplineId": 115,
      "disciplineName": "Men Doubles C",
      "partner": ""
    },
    "Mixed doubles": {
      "disciplineId": 121,
      "disciplineName": "Mixed Doubles A",
      "partner": ""
    }
  },
  "teams": [
    {
      "poolId": 105,
      "poolName": "Men Singles A",
      "teamId": 472,
      "teamName": "Test Player 1",
      "givenUp": true,
      "registeredForDiscipline": {
        "disciplineType": "Singles",
        "disciplineId": 105,
        "disciplineName": "Men Singles A"
      }
    }
  ],
  "registrationGroup": "Test team 1",
  "registrationGroupContactPlayer": "Yes",
  "paymentBalance": "EUR 0",
  "personEmail": "sjoerdsmink@gmail.com",
  "personName": "Sjoerd Smink",
  "boughtProducts": []
}

Group

Groups (a.k.a. RegistrationGroup) can be used for registration. The player indicates which group he/she belongs to, and a contact person for that group can be appointed.

Group Object

name
string Name of the group
country
string Country of the group
Group example

https://www.tournia.net/api/v2/test/groups/GROUP_ID

# Response Object
{
  "groupId": 47,
  "name": "Test team 1",
  "country": "NL"
}

Discipline

When a Player registers, he/she has to indicate in which Discipline he/she is playing. The tournament organization can configure the Discipline Types (e.g. "Singles") and Disciplines (e.g. "Men Singles A").

Discipline Object

name
string Name of the discipline.
pools
array The connected Pool (see next section). The key is the poolId and value the pool name.
Discipline example

https://www.tournia.net/api/v2/test/disciplines/DISCIPLINE_ID

# Response Object
{
  "disciplineId": 105,
  "name": "Men Singles A",
  "pools": {
    "105": "Men Singles A"
  }
}

Pool

The Pool is similar to a Discipline, with the only difference that Disciplines are used for the registrations, and Pools are used for the tournaments (matches, teams, etc.). This distinction is made to make it possible to have finals (which is something you don't register for...) and make is easy to combine multiple disciplines to one pool (when there are not enough registrations).

Pool Object

position
integer The order of displaying pools can be changed. Lowest positions are displayed first.
algorithm
string The way new matches are generated.
inputDisciplines
array Registrations of players can be imported automatically. Therefore we need to know which reigistration disciplines will result in which pools. It is possible to have multiple disciplines connected to have multiple pools (many-to-many relation).
totTeams
integer The total number of teams in this pool
nrPlayersInTeam
integer The number of players in a team. I.e. 1 for singles, 2 for doubles.
teams
array Information about the teams in this pool
Pool example

https://www.tournia.net/api/v2/test/pools/POOL_ID

# Response Object
{
  "poolId": 105,
  "position": 0,
  "name": "Men Singles A",
  "algorithm": "swissladder",
  "inputDisciplines": {
    "105": "Men Singles A"
  },
  "totTeams": 6,
  "nrPlayersInTeam": 1,
  "teams": {
    "470": {
      "id": 470,
      "name": "Test Player 4",
      "givenUp": true,
      "nonreadyReason": null,
      "players": [
        {
          "id": 155,
          "name": "Test Player 4",
          "registrationGroup": "Test team 1",
          "gender": "M",
          "hasReplacementPlayer": false
        }
      ]
    },
    "471": {
      "id": 471,
      "name": "Test player 2",
      "givenUp": false,
      "nonreadyReason": null,
      "players": [
        {
          "id": 153,
          "name": "Test player 2",
          "registrationGroup": "Test Team 2",
          "gender": "M",
          "hasReplacementPlayer": false
        }
      ]
    }
  }
}

Team

A team belongs to a pool, and consists of players.

It is possible to add/remove players to a team, set a replacement player or let the team give up. Given up teams won't have new matches, and won't be counted in the ranking.

Team Object

name
string Name of the team, composed of all the player's names
givenUp
boolean Whether the team has given up
nonreadyReason
string Optional reason for giving up
players
array Information about players in the team. In the example you can see that it's possible to have empty spots in the team (indicated by a null).
Team example

https://www.tournia.net/api/v2/test/teams/TEAM_ID

# Response Object
{
  "id": 481,
  "name": "Test Player 10",
  "givenUp": false,
  "nonreadyReason": null,
  "players": [
    {
      "id": 161,
      "name": "Test Player 10",
      "registrationGroup": "Test team 1",
      "gender": "M",
      "hasReplacementPlayer": false,
      "partnerName": "wanted"
    },
    null
  ]
}

Round

A pool has one or more rounds. A match is played in a specific round, in a pool.

Round Object

key
string The key of the result indicates the round number
value
string The value of the result is the name of the round
Round example

https://www.tournia.net/api/v2/test/rounds/POOL_ID

# Response Object
{
  "1": "Round 1",
  "2": "Round 2"
}

Match

A match is pretty self-explanatory. It contains scores, and it has a field to indicate the match has to be played with priority. A match has two teams who play against each other (team1 vs. team2). The match number (localId) is different from the matchId in the database, to make numbering for this specific tournament possible.

A match can be postponed, with optionally a nonreadyReason. Other statuses are: ready, playing, finished or played. These statuses can be set manually, or be called by starting/stopping/finishing a match.

Match Object

localId
string Match number, but different from the database matchId
poolId
string ID of pool where the matches is played in
team1Id
integer ID of team 1
team1Name
string Name of team 1
round
string Round where the matches is played in
status
string Status of the match. Can be: ready, playing, finished, played or postponed.
nonreadyReason
string When a match is postponed, optionally a reason can be given.
priority
boolean Indicator whether this match has to be played with priority.
scoreText
string Score of the match, in textual format
score
array Score of the match, in array format. First scores are for the first set, where 1 indicates the score for team1, and 2 the score for team2.
Match example

https://www.tournia.net/api/v2/test/matches/MATCH_ID

# Response Object
{
  "id": 210,
  "localId": 3,
  "poolId": 105,
  "team1Id": 471,
  "team1Name": "Test player 2",
  "team2Id": 471,
  "team2Name": "Test player 2",
  "poolName": "Men Singles A",
  "round": "Round 1",
  "status": "played",
  "nonreadyReason": null,
  "priority": false,
  "scoreText": "3-21 12-21",
  "score": [
    {
      "1": "3",
      "2": "21"
    },
    {
      "1": "12",
      "2": "21"
    }
  ]
}

Ranking

A tournament always have winners. And it's good to know how you're doing compared to others.

It is possible to have ranking for a specific pool, top-x winners of all pools, ranking of players or ranking of (registration)groups.

Ranking Object

matchesWon
integer Number of matches won
matchesDraw
integer Number of matches in a draw
matchesLost
integer Number of matches lost
setsWon
integer Number of sets won
setsLost
integer Number of sets lost
pointsWon
integer Number of points won
pointsLost
integer Number of points lost
teamId
integer The team with this ranking
players
array Players in the team
matchesPlayed
integer Number of matches in total played
matchesRelative
float Relative score is between -1 en +1, with won matches resulting in a positive score and lost matches in a negative score. Counts first (most important) in ranking.
setsRelative
float Relative score is between 0 en +1, calculated as won sets divided by total sets. Counts second in ranking.
pointsRelative
float Relative score is between 0 en +1, calculated as won points divided by total points. Counts third (least important) in ranking.
rank
integer Rank of this team
Ranking example

https://www.tournia.net/api/v2/test/rankings/pool/POOL_ID

# Response Object
[
  {
    "matchesWon": 1,
    "matchesDraw": 0,
    "matchesLost": 0,
    "setsWon": 2,
    "setsLost": 0,
    "pointsWon": 42,
    "pointsLost": 15,
    "teamId": 474,
    "players": {
      "161": "Test Player 10"
    },
    "givenUp": false,
    "matchesPlayed": 1,
    "matchesRelative": "1.000",
    "setsRelative": "1.000",
    "pointsRelative": "0.737",
    "rank": 1
  },
  {
    "matchesWon": 0,
    "matchesDraw": 0,
    "matchesLost": 0,
    "setsWon": 0,
    "setsLost": 0,
    "pointsWon": 0,
    "pointsLost": 0,
    "teamId": 475,
    "players": {
      "346": "Test Player 4"
    },
    "givenUp": false,
    "matchesPlayed": 0,
    "matchesRelative": "0.000",
    "setsRelative": "0.500",
    "pointsRelative": "0.500",
    "rank": 2
  }
]

Location

A match is played on a location (although it is possible to play a match on an undefined location). This location has a name, and the order for displaying can be set.

Location Object

name
string Name of the location
onHold
boolean Whether the location is on hold (i.e. not usable)
nonreadyReason
string Optional reason for when the location is onHOld
position
integer The order of displaying locations can be changed. Lowest positions are displayed first.
Location example

https://www.tournia.net/api/v2/test/locations/LOCATION_ID

# Response Object
{
  "id": 18,
  "name": "Court 1",
  "onHold": false,
  "nonreadyReason": null,
  "position": 0
}

Announcement

There are two kind of announcements: for new matches, and for a second call (i.e. no-show). When a new match is started, an announcement is automatically created. When a match is finished, the announcement is obsolete, and therefore deleted. When a second call for a specific player is requested, this results in an announcement.

Announcement Object

playerIds
string The players that require the second call
deltaStartTime
integer Time since start of the match
Announcement example

https://www.tournia.net/api/v2/test/announcements

# Response Object
{
  "secondCall": [
    {
      "announcementId": 2942,
      "playerIds": [
        "153"
      ],
      "locationId": 19,
      "location": "Court 2",
      "locationOnHold": false,
      "matchId": 210,
      "localId": 3,
      "team1": {
        "teamId": 471,
        "name": "Test player 2",
        "players": [
          {
            "playerId": 153,
            "name": "Test player 2",
            "currentlyPlaying": false,
            "ready": true
          }
        ]
      },
      "team2": {
        "teamId": 474,
        "name": "Test Player 10",
        "players": [
          {
            "playerId": 161,
            "name": "Test Player 10",
            "currentlyPlaying": false,
            "ready": true
          }
        ]
      },
      "pool": "Men Singles A",
      "round": "Round 1",
      "status": "Played",
      "nonreadyReason": null,
      "priority": false,
      "score": "3-21 12-21",
      "deltaStartTime": 53223290
    }
  ],
  "newMatches": [
    {
      "announcementId": 2941,
      "playerIds": [],
      "locationId": 18,
      "location": "Court 1",
      "locationOnHold": false,
      "matchId": 211,
      "localId": 4,
      "team1": {
        "teamId": 479,
        "name": "Test Player 9",
        "players": [
          {
            "playerId": 160,
            "name": "Test Player 9",
            "currentlyPlaying": true,
            "ready": true
          }
        ]
      },
      "team2": {
        "teamId": 476,
        "name": "Test Player 3",
        "players": [
          {
            "playerId": 154,
            "name": "Test Player 3",
            "currentlyPlaying": true,
            "ready": true
          }
        ]
      },
      "pool": "Ladies Singles A",
      "round": "Round 1",
      "status": "Playing",
      "nonreadyReason": null,
      "priority": false,
      "score": "",
      "deltaStartTime": 519171
    }
  ]
}

Command

Congrats, you made it to the end of this documentation :-) Therefore we have something special for you: we made it easy to combine multiple REST-calls into one request. In the full API reference you can see on the right side for every endpoint a shortcut, e.g. Groups.list or Announcements.remove. Use this shortcut when sending to the command endpoint, and you'll get the same response as the shortcut endpoint.

Command Object

playerIds
string The players that require the second call
deltaStartTime
integer Time since start of the match
Command example

https://www.tournia.net/api/v2/test/commands

# Response Object
Depending on the requested shortcut.