Documentation

Collective Leaderboards

Overview

Collective leaderboards are intended to allow players to anonymously submit score information and then provide statistics on those scores.
It allows you to give contextual information to the player regarding their score compared to the leaderboard, such as:

  • How many people have submitted a score today - "You are the 4th person to score today!"
  • What percentage of people are above/below them - "You are in the top 30% of worldwide players!"
  • Whether they got the best/worst score today/this week/all time - "You got the best score this week!"

Create a Leaderboard

Leaderboards are created at https://wirthwhilegaming.com/developer/leaderboard/create.

Field Description
Leaderboard Name A reference just for you to easily find a leaderboard.
Game The game the leaderboard is for, a game must be set up first.
Score Ordering Whether larger scores or smaller scores are better. Allows the API to return the 'best' score for you without having to check for the largest/smallest score.
Remove Score Out of Range Using this will not add scores outside the range you specify when the API is called.
Minimum Score Allowed Optional - smallest score that can be recorded. Only necessary if removing scores out of range.
Minimum Score Allowed Optional - largest score that can be recorded. Only necessary if removing scores out of range.
Initialise Leaderboard Allows you to set an initial state if your leaderboard exists before using this service.
Current Maximum Score Optional - largest score on your leaderboard currently.
Current Minimum Score Optional - smallest score on your leaderboard currently.
Current Score Count Optional - number of scores on your leaderboard currently.
Current Score Sum Optional - the sum of the scores on your leaderboard currently.
NOTE If you cannot get all of your leaderboard data for initialising, just put in the minimum and maximum scores, a count of 2 and the sum of the minimum and maximum scores. The data should even out over time with those initial values.

How to submit scores

All scores are stored internally as integers, this is reduce any precision errors. If you need to store float values, we suggest determining the precision from within your game. For example:
If you have a maximum of 3 decimal places, then multiply all scores by 1000 when submitting, then when analysing the score data remember to divide those scores by 1000. With a precision of 3, a score of 23.679 would be submitted as 23679 and 43.2 would be submitted as 43200.

Recording a Score

Request

https://wirthwhilegaming.com/api/leaderboard/record_score?leaderboard_key=KEY&score=SCORE&test=1
Field Description
leaderboard_key A 6 character unique identifier for your leaderboard. Can be found at https://wirthwhilegaming.com/developer/leaderboard.
score The player's score as an integer.
test Either a 1 or 0. Used for sending data to the test leaderboard (1) or live leaderboard (0).

Response


{
	"success":true,
	"scores":[
		{
			"score_max":"94",
			"score_min":"54",
			"score_count":"5",
			"score_average":"83",
			"score_best":"94",
			"timeframe":"today",
			"percentile":100
		},
		{
			"score_max":"578",
			"score_min":"0",
			"score_count":"22",
			"score_average":"127",
			"score_best":"578",
			"timeframe":"last_seven_days",
			"percentile":16
		},
		{
			"score_max":"868",
			"score_min":"0",
			"score_count":"40",
			"score_average":"154",
			"score_best":"868",
			"timeframe":"all_time",
			"percentile":10
		}
	]
}

The scores are returned in array of aggregated timeframes.
Field Description
score_max The maximum score for the timeframe.
score_min The minimum score for the timeframe.
score_count The number of scores submitted in the timeframe.
score_average The average score for the timeframe. Calculated as ceil(SUM(score_sum) / SUM(score_count))
score_best Will be the same as score_max or score_min depending on whether you chose ascending or descending sort order for the leaderboard.
timeframe A string representing the time the data is calculated from. These strings will not be changed, but more could be added in the future.
percentile How the player's score compares to the existing data. 100 is the best score and 0 is the worst score. For example a value of 85 means that the player is the top 15% of players.

Score Summary

Request

Used for getting the current leaderboard stats without recording a score.
https://wirthwhilegaming.com/api/leaderboard/get_summary?leaderboard_key=KEY&test=1
Field Description
leaderboard_key A 6 character unique identifier for your leaderboard. Can be found at https://wirthwhilegaming.com/developer/leaderboard.
test Either a 1 or 0. Used for sending data to the test leaderboard (1) or live leaderboard (0).

Response

Returns in the same format as record_score above, except there is no percentile field as there is nothing to compare against.

How charges are calculated

Every 24 hours your daily unpaid leaderboard entries will be charged. You will be charged credits equal to the number of submitted scores divided by 1000 rounded up to the nearest whole number.

For example if you had 1500 scores submitted on one day the charges would be ceiling(1500 / 1000) = 2 credits.