Structure API › Rankings

Returns ranking items with a small summary of the associated participant in the ranking. The items are always ordered by ascending position.

Resource URL

https://api.toornament.com/organizer/v2/ranking-items

HTTP headers

• X-Api-Key

  string

  API key of your application (see Authentication)

• Authorization

  string

  Access token with organizer:result scope (see Authorization)

• Range

  string

  A range of requested items using the items unit. The size of the range can not exceed 50. (see Pagination)

  Example: items=0-49

Query Parameters

• tournament_ids

  array

  Only return ranking items for the given list of tournaments.

  Example: 618965416546776434,618975467354349191

• stage_ids

  array

  A list of stage ids to filter.

  Example: 618965765764577354,618931468547654563

• stage_numbers

  array

  A list of stage numbers to filter.

  Example: 1,3

• group_ids

  array

  A list of group ids to filter.

  Example: 618965314871946714,618932178746476544

• group_numbers

  array

  A list of group numbers to filter.

  Example: 3,4

• user_ids

  array

  One or several player user ids involved in the ranking items to filter.

  Example: 475141143408399456,735147043408391234

• team_ids

  array

  One or several team ids involved in the ranking items to filter.

  Example: 561714159547269773,255149043401714321

• custom_user_identifiers

  array

  One or several custom user identifiers involved in the ranking items to filter.

  Example: acme:account:1234,acme:account:1235

• participant_ids

  array

  One or several participant ids involved in the ranking items to filter.

  Example: 618965416546776434,618975467354349191

• min_rank

  integer

  A minimal rank to filter.

• max_rank

  integer

  A maximal rank to filter.

Request Body

This endpoint does not require a request body.

Response

[206] List of ranking items.

Example

[
    {
        "tournament_id": "378426939508809728",
        "stage_id": "618983668512789184",
        "id": "618983668512789184",
        "group_id": "618983668512789184",
        "number": 2,
        "position": 4,
        "rank": 3,
        "participant": {
            "id": "375143143408309123",
            "name": "Jon Snow",
            "custom_user_identifier": "acme:account:1234",
            "custom_fields": {}
        },
        "points": 17,
        "properties": {
            "wins": 1,
            "draws": 0,
            "losses": 0,
            "played": 1,
            "forfeits": 0,
            "score_for": 0,
            "score_against": 0,
            "score_difference": 0
        }
    }
]

Structure (collection)

• tournament_id

  string

  The id of the tournament that contains this ranking item.

  Example: "378426939508809728"

• stage_id

  string

  The id of the stage that contains this ranking item.

  Example: "618983668512789184"

• id

  string

  The id of the ranking item.

  Example: "618983668512789184"

• group_id

  string

  The id of the group associated to this ranking.

  Example: "618983668512789184"

• number

  integer

  A number used as relative identifier within the ranking. It is determined from the seed attributed to the participant during the placement.

  Example: 2

• position

  integer

  A position used for presentation purposes. It is always unique within the same ranking.

  Example: 4

• rank

  integer|null

  The ranking of the participant in the ranking. Multiple participants can share the same rank if they are tied after involving all configured tiebreakers.

  Example: 3

• participant

  object|null

  The participant identified with this item.

  • id

    string

    The id of the participant.

    Example: "375143143408309123"

  • name

    string

    The name of the participant.

    Max. length: 40 characters

    Example: "Jon Snow"

  • custom_user_identifier

    string|null

    An external custom user identifier. Use the format that suits your needs.

    Max. length: 100 characters

    Example: "acme:account:1234"

  • custom_fields

    object

    The values of the custom fields configured in the tournament using the machine names as keys. For more information, please read the Custom Fields documentation.

    Example: {}

• points

  integer

  A number of points acquired by the participant in the ranking.

  Example: 17

• properties

  object

  A list of ranking metrics (see ranking properties).

  Example: {"wins":1,"draws":0,"losses":0,"played":1,"forfeits":0,"score_for":0,"score_against":0,"score_difference":0}

This endpoint is in legacy mode. Access will soon be deprecated. It is therefore advised to use another endpoint when possible.

Returns ranking items of a stage with a small summary of the associated participant in the ranking. The items are always ordered by ascending position.

Resource URL

https://api.toornament.com/organizer/v2/tournaments/{tournament_id}/stages/{stage_id}/ranking-items

HTTP headers

• X-Api-Key

  string

  API key of your application (see Authentication)

• Authorization

  string

  Access token with organizer:result scope (see Authorization)

• Range

  string

  A range of requested items using the items unit. The size of the range can not exceed 50. (see Pagination)

  Example: items=0-49

Path parameters

• tournament_id

  string

  The id of the tournament you want to retrieve data about.

• stage_id

  string

  The id of the stage you want to retrieve data about.

Query Parameters

• custom_user_identifiers

  array

  One or several custom user identifiers involved in the ranking items to filter.

  Example: acme:account:1234,acme:account:1235

• group_ids

  array

  A list of group ids to filter.

  Example: 618965314871946714,618932178746476544

• group_numbers

  array

  A list of group numbers to filter.

  Example: 3,4

• participant_ids

  array

  One or several participant ids involved in the ranking items to filter.

  Example: 618965416546776434,618975467354349191

Request Body

This endpoint does not require a request body.

Response

[206] List of ranking items.

Example

[
    {
        "id": "618983668512789184",
        "group_id": "618983668512789184",
        "number": 2,
        "position": 4,
        "rank": 3,
        "participant": {
            "id": "375143143408309123",
            "name": "Jon Snow",
            "custom_user_identifier": "acme:account:1234",
            "custom_fields": {}
        },
        "points": 17,
        "properties": {
            "wins": 1,
            "draws": 0,
            "losses": 0,
            "played": 1,
            "forfeits": 0,
            "score_for": 0,
            "score_against": 0,
            "score_difference": 0
        }
    }
]

Structure (collection)

• id

  string

  The id of the ranking item.

  Example: "618983668512789184"

• group_id

  string

  The id of the group associated to this ranking.

  Example: "618983668512789184"

• number

  integer

  A number used as relative identifier within the ranking. It is determined from the seed attributed to the participant during the placement.

  Example: 2

• position

  integer

  A position used for presentation purposes. It is always unique within the same ranking.

  Example: 4

• rank

  integer|null

  The ranking of the participant in the ranking. Multiple participants can share the same rank if they are tied after involving all configured tiebreakers.

  Example: 3

• participant

  object|null

  The participant identified with this item.

  • id

    string

    The id of the participant.

    Example: "375143143408309123"

  • name

    string

    The name of the participant.

    Max. length: 40 characters

    Example: "Jon Snow"

  • custom_user_identifier

    string|null

    An external custom user identifier. Use the format that suits your needs.

    Max. length: 100 characters

    Example: "acme:account:1234"

  • custom_fields

    object

    The values of the custom fields configured in the tournament using the machine names as keys. For more information, please read the Custom Fields documentation.

    Example: {}

• points

  integer

  A number of points acquired by the participant in the ranking.

  Example: 17

• properties

  object

  A list of ranking metrics (see ranking properties).

  Example: {"wins":1,"draws":0,"losses":0,"played":1,"forfeits":0,"score_for":0,"score_against":0,"score_difference":0}

This endpoint is in legacy mode. Access will soon be deprecated. It is therefore advised to use another endpoint when possible.

Returns ranking items of a stage with a small summary of the associated participant in the ranking. The items are always ordered by ascending position.

Resource URL

https://api.toornament.com/organizer/v2/stages/{stage_id}/ranking-items

HTTP headers

• X-Api-Key

  string

  API key of your application (see Authentication)

• Authorization

  string

  Access token with organizer:result scope (see Authorization)

• Range

  string

  A range of requested items using the items unit. The size of the range can not exceed 50. (see Pagination)

  Example: items=0-49

Path parameters

• stage_id

  string

  The id of the stage you want to retrieve data about.

Query Parameters

• custom_user_identifiers

  array

  One or several custom user identifiers involved in the ranking items to filter.

  Example: acme:account:1234,acme:account:1235

• group_ids

  array

  A list of group ids to filter.

  Example: 618965314871946714,618932178746476544

• group_numbers

  array

  A list of group numbers to filter.

  Example: 3,4

• participant_ids

  array

  One or several participant ids involved in the ranking items to filter.

  Example: 618965416546776434,618975467354349191

Request Body

This endpoint does not require a request body.

Response

[206] List of ranking items.

Example

[
    {
        "id": "618983668512789184",
        "group_id": "618983668512789184",
        "number": 2,
        "position": 4,
        "rank": 3,
        "participant": {
            "id": "375143143408309123",
            "name": "Jon Snow",
            "custom_user_identifier": "acme:account:1234",
            "custom_fields": {}
        },
        "points": 17,
        "properties": {
            "wins": 1,
            "draws": 0,
            "losses": 0,
            "played": 1,
            "forfeits": 0,
            "score_for": 0,
            "score_against": 0,
            "score_difference": 0
        }
    }
]

Structure (collection)

• id

  string

  The id of the ranking item.

  Example: "618983668512789184"

• group_id

  string

  The id of the group associated to this ranking.

  Example: "618983668512789184"

• number

  integer

  A number used as relative identifier within the ranking. It is determined from the seed attributed to the participant during the placement.

  Example: 2

• position

  integer

  A position used for presentation purposes. It is always unique within the same ranking.

  Example: 4

• rank

  integer|null

  The ranking of the participant in the ranking. Multiple participants can share the same rank if they are tied after involving all configured tiebreakers.

  Example: 3

• participant

  object|null

  The participant identified with this item.

  • id

    string

    The id of the participant.

    Example: "375143143408309123"

  • name

    string

    The name of the participant.

    Max. length: 40 characters

    Example: "Jon Snow"

  • custom_user_identifier

    string|null

    An external custom user identifier. Use the format that suits your needs.

    Max. length: 100 characters

    Example: "acme:account:1234"

  • custom_fields

    object

    The values of the custom fields configured in the tournament using the machine names as keys. For more information, please read the Custom Fields documentation.

    Example: {}

• points

  integer

  A number of points acquired by the participant in the ranking.

  Example: 17

• properties

  object

  A list of ranking metrics (see ranking properties).

  Example: {"wins":1,"draws":0,"losses":0,"played":1,"forfeits":0,"score_for":0,"score_against":0,"score_difference":0}