Tourney Grounds

API Documentation v3.0

This document describes an API for the web site Tourney Grounds: Five Sails. It contains a few basic API URLs for fetching data stored on the site.

This is the list of all the URL endpoints available in the API. Go fetch!

Where :tournament_id is a tournament identifier.

All API URLs are composed using this pattern:

    https://thrones.tourneygrounds.com/api/:version/:method

This document describes version 3 of the API. This is reflected in the URL by the v3 version selector:

    https://thrones.tourneygrounds.com/api/v3/...

All endpoints deliver their response data in JSON format.

Some endpoints accept additional parameters added as a query string to the base URL.

    https://thrones.tourneygrounds.com/api/v3/:method?:param1=:value1&:param2=:value2...

Date: All date and time data returned by the API are strings on the %Y-%m-%d %H:%M:%S date format, following the ISO 8601 standard. The time returned is UTC timezone.
Float: A real number.
Integer: An integer number.
String: A UTF-8 encoded string. Non ASCII characters are represented as unicode escape sequences on the \uXXXX format.

Below is a detailed list of all URL endpoints in the API and their supported HTTP method.

Returns all tournaments in the database.

    https://thrones.tourneygrounds.com/api/v3/tournaments

Parameter	Data type	Description
`after`	Date	Return only finished tournaments with a `end_time` after the given time.
`page`	Integer	Return the given page of the full result. A maximum of 49 tournaments are returned per request. A `page` of 1 (the default) will return the first 50 tournaments, 2 the next 50, and so on. An empty list signals the end of the result.
`tournament_id`	Integer	Return only the tournament with the given `tournament_id`.

Field	Data type	Description
`tournament_id`	Integer	Internal ID of the tournament.
`tournament_name`	String	Name of the tournament.
`player_count`	Integer	Number of players in the tournament.
`scheduled_time`	Date	Time when the tournament is scheduled to start. The time part will always be `00:00:00`.
`start_time`	Date	Time when the tournament started, if it has started.
`end_time`	Date	Time when the tournament was last updated.
`country`	String	Name of the country the tournament is held in (in English).
`region`	String	Name of the region the tournament is held in (in English). The following regions are defined: Africa Asia Europe North America Oceania South America
`report_mode`	Integer	1 if this tournament is a "report", else 0. Tournament reports have no game data on the site, only the final standings.
`review_verdict`	String	The following verdicts are defined: `legitimate`: This tournament has been reviewed and marked as legitimate. `suspicious`: This tournament has been reviewed and marked as suspicious. `null`: This tournament has no review verdict.
`tournament_tier`	String	This field describes the competitive level of the tournament, as described by the official FFG tournament rules. The following tiers are defined: `relaxed` `formal` `premier`

Returns the player results of a finished tournament with the internal ID of :tournament_id.

The players are returned in descending order of their final position in the tournament.

    https://thrones.tourneygrounds.com/api/v3/tournaments/:tournament_id

Parameter	Data type	Description
`swiss_order`	Integer	If `swiss_order` equals `1`, the players are returned in descending order of their standing after the Swiss rounds, ignoring the results of any elimination rounds. The `topx` values returned are not affected by this. (No effect on tournament reports.)

Field	Data type	Description
`player_id`	Integer	Internal ID of the player.
`player_name`	String	Name of the player.
`faction`	String	Name of the player's faction.
`leader`	String	Name of the player's leader.
`topx`	Integer	An integer greater than 256 if the player did not participate in elimination rounds, otherwise it indicates the top cut the player made it to before being eliminated. I.e. 1 means the tournament winner, 2 means the runner-up, 4 means a semifinalist, and so on. (This field is excluded from tournament reports.)
`points`	Integer	Number of game points earned in the Swiss rounds. (Elimination rounds not included.) (This field is excluded from tournament reports.)
`headtohead`	Integer	1 if the player defeated all other players with the same number of points, otherwise 0. (This field is excluded from tournament reports.)
`sos`	Float	The player's Strength of Schedule from the Swiss rounds. (This field is excluded from tournament reports.)
`esos`	Float	The player's Extended Strength of Schedule from the Swiss rounds. (This field is excluded from tournament reports.)

Returns all finished games in the database.

    https://thrones.tourneygrounds.com/api/v3/games

Parameter	Data type	Description
`after`	Date	Return only games with a `tournament_date` after the given time.
`current_only`	Integer	If `current_only` equals `1`, return only games from the current tournament round. This parameter is only applicable together with the `tournament_id` parameter.
`page`	Integer	Return the given page of the full result. A maximum of 50 tournaments are returned per request. A `page` of 1 (the default) will return the first 50 tournaments, 2 the next 50, and so on. An empty list signals the end of the result.
`player_id`	Integer	Return only games where `player_id` is one of the players of the game.
`topx_only`	Integer	If `topx_only` equals `1`, return only games where `topx` is greater than `0`.
`tournament_id`	Integer	Return only games from the tournament with the given `tournament_id`. Using this parameter will cause all games to be returned, not only finished ones.
`swiss_only`	Integer	If `swiss_only` equals `1`, return only games where `topx` equals `0`.

Field	Data type	Description
`game_id`	Integer	Internal ID of the game.
`tournament_id`	Integer	Internal ID of the tournament where this game was played.
`tournament_date`	Date	Time when the tournament was last updated.
`tournament_name`	String	Name of the tournament.
`tournament_round`	Integer	Round number of the tournament the game was played in.
`table_number`	Integer	Number of the table the game was played on.
`topx`	Integer	If this game was an elimination game, `topx` is equal to the number of players still in the tournament at the time of this game. I.e. 2 means final, 4 semi-final, and so on. Otherwise 0.
`p1_id`	Integer	Internal ID of the first player.
`p1_name`	String	Name of the first player.
`p1_points`	Integer	Number of points awarded to the first player based on the game results.
`p1_faction`	String	Name of the first player's faction.
`p1_leader`	String	Name of the first player's leader.
`p2_id`	Integer	Internal ID of the second player.
`p2_name`	String	Name of the second player.
`p2_points`	Integer	Number of points awarded to the second player based on the game results.
`p2_faction`	String	Name of the second player's faction.
`p2_leader`	String	Name of the second player's leader.