Adds a game result for a played game.

POST

/v1/result

result

Adds a game result for a played game, triggering rating calculation.

It's possible to enter more than two participants, as shown in the example. The Glicko/Elo algorithms don't originally support this - our implementations treat it as 'every entry playing a game against all other entries' and then scale down the total results according to the amount of entries in order to prevent overinflated rating/deviation changes. Due to it being less likely to score your mathematically expected result in a field of, let's say, 20 entries vs. a field of only 2 entries, in practice, rating changes will be slightly less pronounced in larger fields on average. If your type of game/sport/competition lends itself to very large fields, you should consider employing a minimum amount of entries that has to be reached for results to count.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/json

ladderId

integer

optional

Id of the ladder to be referenced. A result must have either a ladderId or a tournamentId.

Example:

tournamentId

integer

optional

Currently unused

ladderEntryIds

array[integer]

required

IDs of all ladder-entries that have participated in this game.

Example:

[123,42,13,7]

entryTeams

array[integer]

optional

Defines teams for the given ladderEntryIds. Members of the same team won't be considered to be playing against each other during rating calculation. In the example case, the ladder entry with the ID 123 is in team 1, 42 is in team 3, and 13 and 7 are in team 2. If some entries are in teams but others aren't, you can use team -1 for those that aren't, instead of giving each their own team. Can be omitted if there are no teams.

Example:

[1,3,2,2]

finishPositions

array[integer]

required

Describes the game's result for the given ladderEntryIds. In the example case, the ladder entry with the ID 123 has won, 42 has come 2nd, and 13 and 7 share a 3rd place. These results are used for rating calculation.

Example:

[1,2,3,3]

data

string

optional

Any additional JSON with data you would like to store for this result. This will be returned as is when you GET this result.

Example:

Example

{
  "ladderId": 0,
  "tournamentId": 0,
  "ladderEntryIds": [
    123,
    42,
    13,
    7
  ],
  "entryTeams": [
    1,
    3,
    2,
    2
  ],
  "finishPositions": [
    1,
    2,
    3,
    3
  ],
  "data": ""
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.competier.net/v1/result' \
--header 'Content-Type: application/json' \
--data-raw '{
    "ladderId": 0,
    "tournamentId": 0,
    "ladderEntryIds": [
        123,
        42,
        13,
        7
    ],
    "entryTeams": [
        1,
        3,
        2,
        2
    ],
    "finishPositions": [
        1,
        2,
        3,
        3
    ],
    "data": ""
}'

Responses

🟢200OK

application/json

Body

number

read-onlyoptional

References a result.

Example:

ladderId

integer

optional

Id of the ladder to be referenced. A result must have either a ladderId or a tournamentId.

Example:

tournamentId

integer

optional

Currently unused

ladderEntryIds

array[integer]

required

IDs of all ladder-entries that have participated in this game.

Example:

[123,42,13,7]

entryNames

array[string]

read-onlyoptional

Names of all ladder-entries that have participated in this game. Name changes after this game happened are not reflected.

Example:

["Alice","Bob","Charlie","Dave"]

entryTeams

array[integer]

optional

Example:

[1,3,2,2]

finishPositions

array[integer]

required

Example:

[1,2,3,3]

oldRatings

array[integer]

read-onlyoptional

Ratings for the given ladderEntryIds before ratingChanges caused by this result were applied.

Example:

[1500,1500,1500,1800]

ratingChanges

array[integer]

read-onlyoptional

Rating changes for the given ladderEntryIds caused by this result.

Example:

[29,3,-12,-20]

reliabilityDeviationChanges

array[integer]

read-onlyoptional

Reliability deviation changes for the given ladderEntryIds caused by this result. This doesn't include reliability deviation increases caused by not having played an

Example:

[123,123,123,123]

volatilityChanges

array[integer]

read-onlyoptional

Currently unused

data

string

optional

Any additional JSON with data you would like to store for this result. This will be returned as is when you GET this result.

Example:

Example

{
  "id": 0,
  "ladderId": 0,
  "tournamentId": 0,
  "ladderEntryIds": [
    123,
    42,
    13,
    7
  ],
  "entryNames": [
    "Alice",
    "Bob",
    "Charlie",
    "Dave"
  ],
  "entryTeams": [
    1,
    3,
    2,
    2
  ],
  "finishPositions": [
    1,
    2,
    3,
    3
  ],
  "oldRatings": [
    1500,
    1500,
    1500,
    1800
  ],
  "ratingChanges": [
    29,
    3,
    -12,
    -20
  ],
  "reliabilityDeviationChanges": [
    123,
    123,
    123,
    123
  ],
  "volatilityChanges": [
    0
  ],
  "data": ""
}

🟠400Bad request

🟠401Unauthorized

🟠429Too Many Requests

Modified at 2025-01-04 19:37:12

Gets ladder entries.

Deletes a game result by rolling it back, reverting rating changes.