Submit a time

Description

When an user finishes a level, a race or similar, use this endpoint to submit the user time. GameRank maintains the user's personal best, the podium of all submitted times, etc.

Endpoint

POST https://api.gamerank.io/timeboard/submit

Request JSON body

Field	Type	Optional	Description
time	int		User's new time entry to submit (in millisecond)
username	string		Displayable user's name
userid	string	Yes	User's unique identifier. Alpha-numerical ASCII characters only. If not provided: a random id is generated.
return_best	bool	Yes	If set to true, the response will contain the player's current best submitted time and their current position in the timeboard.

Example

{
    "time": 159100,
    "username": "John Doe",
    "userid": "1289",
    "return_best": false
}

Response JSON body

Field	Type	Description
userid	string	User id used to store this time.
best_position	int	Best position of the user in the leaderboard. Only present if return_best is set to true in the request.
best	int	Best submitted time for this user (in millisecond). Only present if return_best is set to true in the request.
best_creation_time	millisecond timestamp	UTC timestamp (in millisecond) at which the player submitted their best time. Only present if return_best is set to true in the request.
is_new_best	bool	true if the time entry just submitted is the new personal best of the user. Only present if return_best is set to true in the request.

{
    "userid": "1289",

    // Following fields are only present if `return_best` is set
    // to `true` in the request.

    "best_position": 43,
    "best": 123716,
    "best_creation_time": 1730026754899,
    "is_new_best": false
}

HTTP status code

HTTP status	Reason(s)
200	• OK, time submitted
400	• Malformed JSON • Empty username • Invalid user ID format • Invalid leaderboard type (e.g. sending a score to a time leaderboard)
404	• Unknown API key / timeboard
500	• Server Error, please contact support@gamerank.io