Matches (NBA Live 18)

Endpoints

GET /tournaments/{tournament_id}/matches
Retrieve matches of a tournament.
Simple Access
GET /tournaments/{tournament_id}/matches/{id}
Retrieve a single match of a tournament.
Simple Access
GET /disciplines/{discipline_id}/matches
Get a list of matches out of their tournament and corresponding to a discipline.
Simple Access

GET /tournaments/{tournament_id}/matches

Simple Access

Returns the matches of the given tournament using various filters. If the match type is "ffa", this list is limited to the first 4 opponents ordered by their position.

Resource URL

https://api.toornament.com/viewer/v2/tournaments/{tournament_id}/matches

HTTP headers

X-Api-Key
string
API key of your application (see Authentication)
Range
string
A range of requested items using the matches unit. The size of the range cannot exceed 128. (see Pagination)
Example: matches=0-127

Path parameters

tournament_id
string
The id of the tournament for which matches must be retrieved

Query Parameters

stage_ids
array
One or several stage ids to filter
Example: 618965765764577354,618931468547654563
stage_numbers
array
One or several stage numbers to filter
Example: 1,3
group_ids
array
One or several group ids to filter
Example: 618965314871946714,618932178746476544
group_numbers
array
One or several group numbers to filter
Example: 2,4
round_ids
array
One or several round ids to filter
Example: 618943519431786343,618965178941654763
round_numbers
array
One or several round numbers to filter
Example: 1,2
statuses
array
One or several match statuses to filter
Example: pending,running
is_scheduled
boolean
Whether to include or exclude scheduled matches
Possible values: 0, 1
scheduled_before
datetime
A datetime to include all matches scheduled before or at the datetime
Format: RFC 3339 (combined date, time and utc offset)
Example: 2015-12-31T00:00:00+00:00
scheduled_after
datetime
A datetime to include all matches scheduled after or at the datetime
Format: RFC 3339 (combined date, time and utc offset)
Example: 2015-12-31T00:00:00+00:00
participant_ids
array
One or several participant ids involved in the matches to filter
Example: 618965416546776434,618975467354349191
sort
string
A method to sort the filtered data. Structure sorting uses the stage, group, round and match numbers. Schedule sorting uses the scheduled date. Latest results sorting uses the date at which the matches were played (not scheduled).
Possible values: structure, schedule, latest_results
Default: structure

Request Body

This endpoint doesn't require a request body.

Response

[206] Matches retrieved

Example

[
    {
        "id": "618954615761465416",
        "stage_id": "618983668512789184",
        "group_id": "618985165765456465",
        "round_id": "618965146546456651",
        "number": 2,
        "type": "duel",
        "status": "pending",
        "scheduled_datetime": "2015-12-31T00:00:00+00:00",
        "played_at": "2015-12-31T00:00:00+00:00",
        "opponents": [
            {
                "number": 1,
                "position": 1,
                "result": "win",
                "rank": 3,
                "forfeit": false,
                "score": 15,
                "participant": {
                    "id": "375143143408309123",
                    "name": "Jon Snow",
                    "custom_fields": {
                        "country": "GB",
                        "logo": {
                            "logo_small": "url_to_small_image",
                            "logo_medium": "url_to_medium_image",
                            "logo_large": "url_to_large_image"
                        }
                    }
                }
            }
        ]
    }
]

Structure (collection)

id
string
The id of the match and the match (they both share the same id).
Example: "618954615761465416"
stage_id
string
The id of the stage that contains this match
Example: "618983668512789184"
group_id
string
The id of the group that contains this match
Example: "618985165765456465"
round_id
string
The id of the round that contains this match
Example: "618965146546456651"
number
integer
The match number (a relative identifier within a round)
Example: 2
type
string
The type of match
Possible values: duel, ffa, bye
status
string
The status of the match
Possible values: pending, running, completed
scheduled_datetime
datetime|null
The scheduled date of the match
Format: RFC 3339 (combined date, time and utc offset)
Example: "2015-12-31T00:00:00+00:00"
played_at
datetime|null
The timestamp on which the match was played (a result was provided)
Format: RFC 3339 (combined date, time and utc offset)
Example: "2015-12-31T00:00:00+00:00"
opponents
array[object]
List of match opponents.
- number
  integer
  A number started from 1 to the numbers of opponent used as relative identifier within the ranking.
  Example: 1
- position
  integer
  Optional
  The position of the participant in the ranking. It is always unique and cannot be shared between mulitple participants. Tied participants have their position determined by their number.
  Example: 1
- result
  string|null
  The match result of the opponent
  Possible values: win, draw, loss
- rank
  integer|null
  The rank of the participant in the ranking. Multiple participants can share the same rank if they are tied after applying all configured tiebreakers.
  Example: 3
- forfeit
  boolean
  Whether the opponent is forfeit
  Example: false
- score
  integer|null
  The score of the opponent
  Example: 15
- participant
  object|null
  - id
    string
    The id of the participant
    Example: "375143143408309123"
  - name
    string
    The participant name (maximum 40 characters)
    Example: "Jon Snow"
  - custom_fields
    object
    The country and logo custom fields of the participant
    - country
      string|null
      The country of the participant
      Format: ISO 3166-1 alpha-2
      Example: "GB"
    - logo
      object|null
      The participant logo on every available formats.
      Example: {"logo_small":"url_to_small_image","logo_medium":"url_to_medium_image","logo_large":"url_to_large_image"}

GET /tournaments/{tournament_id}/matches/{id}

Simple Access

Returns a match by the given id with games. If the match type is "ffa", games are limited to the first 4 opponents ordered by their position.

Resource URL

https://api.toornament.com/viewer/v2/tournaments/{tournament_id}/matches/{id}

HTTP headers

X-Api-Key
string
API key of your application (see Authentication)

Path parameters

tournament_id
string
The id of the tournament for which matches must be retrieved
id
string
The id of the match to retrieve

Query Parameters

This endpoint doesn't have any query parameters.

Request Body

This endpoint doesn't require a request body.

Response

[200] Match retrieved

Example

{
    "id": "618954615761465416",
    "stage_id": "618983668512789184",
    "group_id": "618985165765456465",
    "round_id": "618965146546456651",
    "number": 2,
    "type": "duel",
    "status": "pending",
    "scheduled_datetime": "2015-12-31T00:00:00+00:00",
    "played_at": "2015-12-31T00:00:00+00:00",
    "public_note": "A note on\ntwo lines\n",
    "opponents": [
        {
            "number": 1,
            "position": 1,
            "result": "win",
            "rank": 3,
            "forfeit": false,
            "score": 15,
            "participant": {
                "id": "375143143408309123",
                "name": "Jon Snow",
                "custom_fields": {
                    "country": "GB",
                    "logo": {
                        "logo_small": "url_to_small_image",
                        "logo_medium": "url_to_medium_image",
                        "logo_large": "url_to_large_image"
                    }
                }
            }
        }
    ],
    "games": [
        {
            "number": 1,
            "status": "pending",
            "opponents": [
                {
                    "number": 1,
                    "position": 1,
                    "result": "win",
                    "rank": 3,
                    "forfeit": false,
                    "score": 15
                }
            ]
        }
    ]
}

Structure (object)

id
string
The id of the match and the match (they both share the same id).
Example: "618954615761465416"
stage_id
string
The id of the stage that contains this match
Example: "618983668512789184"
group_id
string
The id of the group that contains this match
Example: "618985165765456465"
round_id
string
The id of the round that contains this match
Example: "618965146546456651"
number
integer
The match number (a relative identifier within a round)
Example: 2
type
string
The type of match
Possible values: duel, ffa, bye
status
string
The status of the match
Possible values: pending, running, completed
scheduled_datetime
datetime|null
The scheduled date of the match
Format: RFC 3339 (combined date, time and utc offset)
Example: "2015-12-31T00:00:00+00:00"
played_at
datetime|null
The timestamp on which the match was played (a result was provided)
Format: RFC 3339 (combined date, time and utc offset)
Example: "2015-12-31T00:00:00+00:00"
public_note
string|null
Public note of a match, written by the organizer.
Example: "A note on\ntwo lines\n"
opponents
array[object]
List of match opponents.
- number
  integer
  A number started from 1 to the numbers of opponent used as relative identifier within the ranking.
  Example: 1
- position
  integer
  Optional
  The position of the participant in the ranking. It is always unique and cannot be shared between mulitple participants. Tied participants have their position determined by their number.
  Example: 1
- result
  string|null
  The match result of the opponent
  Possible values: win, draw, loss
- rank
  integer|null
  The rank of the participant in the ranking. Multiple participants can share the same rank if they are tied after applying all configured tiebreakers.
  Example: 3
- forfeit
  boolean
  Whether the opponent is forfeit
  Example: false
- score
  integer|null
  The score of the opponent
  Example: 15
- participant
  object|null
  - id
    string
    The id of the participant
    Example: "375143143408309123"
  - name
    string
    The participant name (maximum 40 characters)
    Example: "Jon Snow"
  - custom_fields
    object
    The country and logo custom fields of the participant
    - country
      string|null
      The country of the participant
      Format: ISO 3166-1 alpha-2
      Example: "GB"
    - logo
      object|null
      The participant logo on every available formats.
      Example: {"logo_small":"url_to_small_image","logo_medium":"url_to_medium_image","logo_large":"url_to_large_image"}
games
array[object]
List of match games.
- number
  integer
  A number started from 1 to the numbers of opponent used as relative identifier within the ranking.
  Example: 1
- status
  string
  The status of the match-game
  Possible values: pending, running, completed
- opponents
  array[object]
  List of match game opponents.
  - number
    integer
    A number started from 1 to the numbers of opponent used as relative identifier within the ranking.
    Example: 1
  - position
    integer
    The unique position of the participant in the ranking.
    Example: 1
  - result
    string|null
    The game result of the opponent
    Possible values: win, draw, loss
  - rank
    integer|null
    The rank of the participant in the ranking. Multiple participants can share the same rank if they are tied after applying all configured tiebreakers.
    Example: 3
  - forfeit
    boolean
    Whether the opponent is forfeit
    Example: false
  - score
    integer|null
    The score of the opponent
    Example: 15

GET /disciplines/{discipline_id}/matches

Simple Access

Retrieve a collection of matches from a specific discipline, filtered and sorted by the given query parameters. If the match type is "ffa", this list is limited to the first 4 opponents ordered by their position.

Resource URL

https://api.toornament.com/viewer/v2/disciplines/{discipline_id}/matches

HTTP headers

X-Api-Key
string
API key of your application (see Authentication)
Range
string
A range of requested items using the matches unit. The size of the range cannot exceed 128. (see Pagination)
Example: matches=0-127

Path parameters

discipline_id
string
The string id of the discipline

Query Parameters

is_featured
boolean
Whether to include or exclude featured tournaments
Possible values: 0, 1
statuses
array
One or several match statuses to filter
Example: pending,running
scheduled_before
datetime
A datetime to include all matches scheduled before or at the datetime
Format: RFC 3339 (combined date, time and utc offset)
Example: 2015-12-31T00:00:00+00:00
scheduled_after
datetime
A datetime to include all matches scheduled after or at the datetime
Format: RFC 3339 (combined date, time and utc offset)
Example: 2015-12-31T00:00:00+00:00
participant_ids
array
One or several participant ids involved in the matches to filter
Example: 618965416546776434,618975467354349191
tournament_ids
array
One or several tournament ids owned in the matches to filter
Example: 378426939508809728,375143143408309123
sort
string
A method to sort the filtered data. Structure sorting uses the stage, group, round and match numbers. Schedule sorting uses the scheduled date. Latest results sorting uses the date at which the matches were played (not scheduled).
Possible values: structure, schedule, latest_results
Default: structure

Request Body

This endpoint doesn't require a request body.

Response

[206] Matches retrieved

Example

[
    {
        "id": "618954615761465416",
        "stage_id": "618983668512789184",
        "group_id": "618985165765456465",
        "round_id": "618965146546456651",
        "number": 2,
        "type": "duel",
        "status": "pending",
        "scheduled_datetime": "2015-12-31T00:00:00+00:00",
        "played_at": "2015-12-31T00:00:00+00:00",
        "tournament": {
            "id": "378426939508809728",
            "name": "My Weekly Tournament",
            "full_name": "My Weekly Tournament - Long title"
        },
        "opponents": [
            {
                "number": 1,
                "position": 1,
                "result": "win",
                "rank": 3,
                "forfeit": false,
                "score": 15,
                "participant": {
                    "id": "375143143408309123",
                    "name": "Jon Snow",
                    "custom_fields": {
                        "country": "GB",
                        "logo": {
                            "logo_small": "url_to_small_image",
                            "logo_medium": "url_to_medium_image",
                            "logo_large": "url_to_large_image"
                        }
                    }
                }
            }
        ]
    }
]

Structure (collection)

id
string
The id of the match and the match (they both share the same id).
Example: "618954615761465416"
stage_id
string
The id of the stage that contains this match
Example: "618983668512789184"
group_id
string
The id of the group that contains this match
Example: "618985165765456465"
round_id
string
The id of the round that contains this match
Example: "618965146546456651"
number
integer
The match number (a relative identifier within a round)
Example: 2
type
string
The type of match
Possible values: duel, ffa, bye
status
string
The status of the match
Possible values: pending, running, completed
scheduled_datetime
datetime|null
The scheduled date of the match
Format: RFC 3339 (combined date, time and utc offset)
Example: "2015-12-31T00:00:00+00:00"
played_at
datetime|null
The timestamp on which the match was played (a result was provided)
Format: RFC 3339 (combined date, time and utc offset)
Example: "2015-12-31T00:00:00+00:00"
tournament
object
The tournament context.
- id
  string
  A unique identifier for the tournament
  Example: "378426939508809728"
- name
  string
  The name of the tournament (maximum 30 characters)
  Example: "My Weekly Tournament"
- full_name
  string|null
  The complete name of the tournament (maximum 80 characters)
  Example: "My Weekly Tournament - Long title"
opponents
array[object]
List of match opponents.
- number
  integer
  A number started from 1 to the numbers of opponent used as relative identifier within the ranking.
  Example: 1
- position
  integer
  Optional
  The position of the participant in the ranking. It is always unique and cannot be shared between mulitple participants. Tied participants have their position determined by their number.
  Example: 1
- result
  string|null
  The match result of the opponent
  Possible values: win, draw, loss
- rank
  integer|null
  The rank of the participant in the ranking. Multiple participants can share the same rank if they are tied after applying all configured tiebreakers.
  Example: 3
- forfeit
  boolean
  Whether the opponent is forfeit
  Example: false
- score
  integer|null
  The score of the opponent
  Example: 15
- participant
  object|null
  - id
    string
    The id of the participant
    Example: "375143143408309123"
  - name
    string
    The participant name (maximum 40 characters)
    Example: "Jon Snow"
  - custom_fields
    object
    The country and logo custom fields of the participant
    - country
      string|null
      The country of the participant
      Format: ISO 3166-1 alpha-2
      Example: "GB"
    - logo
      object|null
      The participant logo on every available formats.
      Example: {"logo_small":"url_to_small_image","logo_medium":"url_to_medium_image","logo_large":"url_to_large_image"}