Leaderboards API
FitnessSyncer Leaderboards allow for device independent competitions on participant’s data. This API allows for the management of the competitions.
List Leaderboards
This method lists all Leaderboards for a user, ranging from those the user owns, is participating in, and also those that are pending approval.
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/leaderboards/"Request Parameters
None
Response
The body with the Leaderboard List Result.
Get Leaderboard
This method gets a Leaderboard by id.
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/leaderboards/id"Request Parameters
None
Response
The body of Leaderboard Item Result.
Create Leaderboard
This method creates a Leaderboard.
Request Parameters
A body containing a Leaderboard
How participants are ranked is set here and cannot be changed afterward, because it is what each participant agrees to. A Data Field that adds up, such as steps, is ranked on its total. A measurement, such as weight, is ranked on its average, its best single reading, or its change from the first reading, and the lowerWins property says which direction wins. A scored Leaderboard gives points to each of its scoringFields, which may come from more than one data type.
To create the Leaderboard for an organization rather than as the user’s own, send the organization’s id in organization. The user must be that organization’s Owner or an Administrator, or the request is refused with NotPermitted (403). The Leaderboard is then the organization’s, organized and billed through the Owner who pays for it, so the user need not be a FitnessSyncer Pro subscriber. An organization’s Owner and Administrators may then update and delete it and add users to it.
Response
The body with the Id Result.
Update Leaderboard
This method updates a Leaderboard.
The Data Fields, the scoring and the ranking (rankBy, lowerWins, hideValues and scoringDailyLimit) are kept from the original, whatever is sent. To change them, create a new Leaderboard.
Request Parameters
A body containing a Leaderboard
Response
The body with the Id Result.
Delete Leaderboard
This method deletes a Leaderboard.
Example request
curl -X DELETE -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/leaderboards/id"Request Parameters
None
Response
The body with the Id Result.
Get Leaderboard Data
This method acquires the data associated with a Leaderboard.
This data can be requested in an easy to consume JSON format by using the Accept Header application/json or as a CSV by using the Accept Header text/csv.
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/leaderboards/id/data"| Query Parameter Name | Description |
|---|---|
| limit | How many participants to return, in ranking order. Without it every participant is returned, except on a Leaderboard run by an organization with an Enterprise license, where 100 are returned unless asked otherwise and never more than 1000. Less than 1 is refused with CouldNotParseBody. |
| offset | How many participants, in ranking order, to skip before the page starts. Default is 0. Less than 0 is refused with CouldNotParseBody. |
The caller’s own participant is always returned as well, after the page, when it is not on it, and total says how many participants the caller may see in all. On a Leaderboard that shows only Teams, a participant receives only the members of their own team and groupings; the organizer, and on an organization’s Leaderboard its Owner and Administrators, receive everyone. On an organization’s Leaderboard, a Group lead who does not take part receives only the members of the groups they lead, and one who takes part receives those members as well as what any participant receives. A Leaderboard that nests its groupings also returns nestedGroups, its group standings at each level.
Response
If the Accept header is not specified or is application/json, the body with the Leaderboard Data Result.
If the Accept header text/csv, a CSV representation of the data will be returned.
Get Leaderboard Classic Data
This method acquires the participants of a Leaderboard along with their scored values, already sorted into ranking order. It is a flattened, table-shaped alternative to Get Leaderboard Data, intended for simple displays that only need a ranked list of participants and their values.
Fields
| JSON Item | Data Type | Description |
|---|---|---|
| nestedGroups | Leaderboard Nested Groups | |
| total | Integer | How many participants the caller may see in all, of which entries is one page. |
| entries | Array of Object | The participants, in ranked order. |
Fields of entries
| JSON Item | Data Type | Description |
|---|---|---|
| participant | String | Display name of the participant. |
| rank | Integer | The participant’s place; omitted for a participant who is not ranked yet. |
| you | Boolean | True on the caller’s own participant, and omitted on everyone else. |
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/leaderboards/id/board/classic"| Query Parameter Name | Description |
|---|---|
| limit | How many participants to return, in ranking order, as for Get Leaderboard Data. |
| offset | How many participants, in ranking order, to skip before the page starts. Default is 0. |
Response
The body will contain an entries field, which is an array of the participants in ranked order. Each entry has a participant field with the participant’s display name, plus one field per scored series on the Leaderboard, keyed by that series’ label.
If the Leaderboard does not exist or you are not a participant of it, a 404 will be returned.
Get Leaderboard User Preferences
This method acquires the user preferences for Leaderboard.
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/leaderboards/id/user/preference"Request Parameters
None
Response
The body with the Leaderboard User Preference.
Update Leaderboard User Preferences
This method updates the user preferences for Leaderboard.
Request Parameters
A body containing a Leaderboard User Preference
Response
The body with the Leaderboard User Preference.
Add User to Leaderboard
This method adds a user to a Leaderboard.
Request Parameters
A body containing a Leaderboard
This also takes an optional sendInvitationEmails query string which if set to false, will not send e-mail notifications to the user.
Response
The body with the Id Result.
Accept a Leaderboard Invitation
This accepts an invitation to a Leaderboard.
Calling this API implies that the user has consented to this action. The user must have been shown all of the information associated with the Leaderboard and told that their information will be visible to all users of the Leaderboard. Furthermore, for absolute data such as weight, the user should be informed not to share this information unless they truly trust the person or organization administering the Leaderboard.
Request Parameters
A body containing a Leaderboard
This also takes an optional team query string, for a Leaderboard whose participants choose their own team. It must be one of the Leaderboard’s team names.
Response
The body with the Id Result.
Remove the Current User from a Leaderboard
This method deletes the current user from the Leaderboard.
Example request
curl -X DELETE -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/leaderboards/id/user"Request Parameters
None
Response
The body with the Id Result.
Remove Users from a Leaderboard (Administrator)
This method deletes the specified user(s) from the Leaderboard.
Request Parameters
Body of Leaderboard User
Response
The body with the Id Result.
Types
Leaderboard
| JSON Item | Data Type | Description |
|---|---|---|
| id | String | This is the unique id for this leaderboard. |
| name | String | This is the name of the Leaderboard. This must be unique. |
| description | String | Description of the Leaderboard |
| granularity | String | What is the granularity you wish for this to run at? Must be one of: DAY, WEEK, or MONTH |
| userLimit | Long | This is the user limit for this leaderboard. It is set by FitnessSyncer when the Leaderboard is created, and any value sent is ignored. For a Leaderboard organization there is effectively no limit unless its agreement sets a participant cap; adding users beyond the limit that applies is refused with LeaderboardLimitExceeded. A coach’s Leaderboard made from one of their programs or tags is not held to it, and takes that program’s or tag’s clients, however many; anyone else is refused with LeaderboardCoachGroupClientsOnly. |
| Boolean | Should we send periodic e-mail notifications? | |
| anyoneCanSignUp | Boolean | By default, the Leaderboard will only allow users who have been explicitly invited. With this option enabled, anyone with a FitnessSyncer account can sign up up-to the limit. |
| chartLineGranularity | Boolean | Should the Leaderboard include the Line Chart per Granularity? |
| chartTableGranularity | Boolean | Should the Leaderboard include the Table per Granularity? |
| chartClassicLeaderboard | Boolean | Should the leaderboard include the Classic Leaderboard View? |
| relative | Boolean | True if the graphs should be relative progress; this disables Group Goals and Classic Leaderboards. This can only be set on creation and cannot be toggled. Not applicable to scoring boards. |
| groupGoal | Double | FitnessSyncer Leaderboards can be configured to be both a challenge for individuals or for a group. If set to a non-negative value, this setting enables group challenges and this is the value for which the primary data field must exceed. Not applicable to scoring boards. On an update, omitting this keeps the stored goal, and -1 or null removes it. |
| scoringField | String | This is the scoring field type. If this is null, this is a standard metric-based leaderboard. If this is set to a value, this is a custom Leaderboard. See the Descriptions API. |
| scoringWeights | Any | If scoringField is specified, these are the scoring weights for each of the DataFields. |
| dataField | Array of String | Data Field for this Leaderboard. The first element is the primary comparison value whereas the others are used for tabular visualization. |
| startDate | Long | Start Date of the Leaderboard in milliseconds since Epoch |
| endDate | Long | End Date of the Leaderboard in milliseconds since Epoch |
| publicLeaderboard | Boolean | True if this Leaderboard is publicly visible. If true, you can access it at https://www.fitnesssyncer.com/leaderboards?board={id} without logging in. |
| scoringFields | Array of String | The scored Data Fields in the order they are shown. With a scoringField preset these are the fields of the preset; without one, any Data Fields that add up, from one or more data types, each with its points in scoringWeights. This can only be set on creation. |
| scoringDailyLimit | Double | The most points one participant can earn in a day on a scored Leaderboard. Omit for no limit. This can only be set on creation. |
| rankBy | String | What participants are ranked on. Must be one of: Total, Average, Best, Change, PercentChange, Score. Total is the only value allowed for a Data Field that adds up, such as steps; it is not allowed for a measurement, such as weight. Score is set for a scored Leaderboard. When omitted, it is derived from the Data Field and from relative. This can only be set on creation. |
| lowerWins | Boolean | True if the lowest value wins, which applies to a Leaderboard ranked on a measurement. A participant with no data is never ranked, whichever direction wins. This can only be set on creation. |
| hideValues | Boolean | True if actual values are never shown to other participants. A Leaderboard ranked on Change or PercentChange shows the change only; any other shows the ranking only. This can only be set on creation. |
| teams | Boolean | True if participants are grouped into teams that are ranked against each other. |
| teamNames | Array of String | The names of the teams. A name may contain a comma. |
| groupings | Array of String | The names of the groupings participants are ranked by beyond their team, such as Region or Department, in the order they are shown. Each grouping is ranked by the same rule as the teams. A participant’s value in each is set with the attributes of the add users request. On an update, the groupings sent replace the existing ones, and omitting this clears them. |
| nesting | Array of String | The groupings shown as groups within groups, outermost first, such as Region, then Department, then the team. Each entry is the name of one of the groupings, or an empty string for the team; any other name is dropped. Each level is ranked within the group above it. On an update, the nesting sent replaces the existing one, and omitting this clears it. |
| noRecentDataDays | Integer | On a Leaderboard run by an organization, how many days without data put a participant in the organizer’s participation report as having no recent data. 5 by default; a value outside 2 to 60 is brought within it. On an update, omitting this keeps the stored value. |
| checkpoints | Array of Leaderboard Checkpoint | Named stops on the way to the team goal, in order from the start, such as the sites of a company walking the distance between them. A checkpoint is reached when everyone’s running total equals or passes its value. Allowed only on a Leaderboard ranked on its Total of steps or of a distance; the values must be positive and strictly increasing, and while groupGoal is set the last must be at or below it. Anything else is refused with LeaderboardCheckpointsInvalid, whose description says what is wrong. Checkpoints are kept when groupGoal is removed, and are shown again when it is set. On an update, omitting this keeps the stored checkpoints and an empty array removes them. |
| startName | String | What the start of the route is called, such as the head office. Omitted when not set. On an update, omitting this keeps the stored name and an empty string removes it. |
| finishName | String | What the finish of the route is called; the finish is groupGoal. Omitted when not set. On an update, omitting this keeps the stored name and an empty string removes it. |
| stepsPerKilometer | Integer | On a Leaderboard of steps, how many steps a kilometer of the route is worth, which is how checkpoints and the finish are spoken of as distances. 1312 by default, a walking stride of 0.76 meters. A value outside 500 to 3000 is refused with LeaderboardCheckpointsInvalid. On an update, omitting this keeps the stored value. |
| startLatitude | Double | Where the route starts, used only to work out the distances along it; it says nothing about any participant. Present only with startLongitude. A latitude outside -90 to 90 or a longitude outside -180 to 180 is refused with LeaderboardCheckpointsInvalid. On an update the place changes only when startLatitude and startLongitude are sent together, null in both removing it; omitting either keeps the stored place. |
| startLongitude | Double | Where the route starts. Present only with startLatitude, and written and kept with it. |
| finishLatitude | Double | Where the route finishes, used only to work out the distances along it. Present only with finishLongitude, and refused, changed and kept as startLatitude is. |
| finishLongitude | Double | Where the route finishes. Present only with finishLatitude, and written and kept with it. |
| teamRace | Boolean | Whether each team travels the whole route on its own, a race between teams, rather than everyone together. It applies only while teams is true and the Leaderboard has checkpoints and a team goal, and then groupGoal is one team’s finish and each team’s value, summed or averaged as teamSum says, is placed on the route. False by default. On an update, omitting this keeps the stored value. |
| checkpointEmail | String | Who is sent an e-mail when the Leaderboard, or a team in a team race, reaches a checkpoint or the finish. One of: Nobody, Organizer, Everyone. Organizer is the Leaderboard’s organizer, an organization’s Owner on its Leaderboard. Everyone is every participant who has not turned the Leaderboard’s e-mail off, and in a team race the members of the team that reached the stop. Each stop is announced once, and of several reached together only the furthest; a stop is known by its name, so changing its value does not announce it again; a stop reached more than a week before is not announced. Nobody by default; an unknown value is Nobody. On an update, omitting this keeps the stored value. |
| contact | String | Whom participants are told to contact about the Leaderboard, such as when their team or group is wrong. It must be an e-mail address or an http or https web address of at most 255 characters; anything else is refused with CouldNotParseBody. On an update, omitting this clears it. It is omitted when not set. |
| emailSubject | String | The subject of this Leaderboard’s invitation e-mails, in place of the standard one. Used only on a Leaderboard run by an organization with an Enterprise license. One line of at most 150 characters; anything else is refused with CouldNotParseBody. On an update, omitting this clears it. |
| emailIntroduction | String | Text shown above the standard invitation in this Leaderboard’s invitation e-mails, a blank line starting a new paragraph; the standard invitation, with what is shared and how to accept, always follows. Used only on a Leaderboard run by an organization with an Enterprise license. At most 2000 characters; a longer value is refused with CouldNotParseBody. On an update, omitting this clears it. |
| logo | String | An https web address of the logo shown at the top of this Leaderboard’s invitation e-mails. Used only on a Leaderboard run by an organization with an Enterprise license. At most 1000 characters; anything that is not an https address is refused with CouldNotParseBody. On an update, omitting this clears it. |
| participantsChooseTeam | Boolean | True if each participant chooses a team when accepting; false if the organizer assigns them. |
| teamSum | Boolean | True if a team is counted as the sum of its members; false, the default, if it is counted as the average of its members. |
| organization | String | On creation, the id of the organization this Leaderboard is created for, as shown in the address of the organization’s page on FitnessSyncer.com; omit it for the user’s own Leaderboard. The user must be that organization’s Owner or an Administrator, or creation is refused with NotPermitted. It is ignored on an update, since a Leaderboard’s organization cannot change, and it is not returned. |
| averageOverMembers | Boolean | True if the average of a team or group divides by every member who has accepted, a member with no data counting as zero; false if it divides by the members who have data. Every Leaderboard created now is true, and a Leaderboard created earlier stays false. It cannot be set or changed. Read-only. |
| display | Array of String | The representations shown for this Leaderboard, in display order. Each must be one of: Standings, Teams, Trend, Table, Journey. When present, it takes precedence over chartLineGranularity, chartTableGranularity and chartClassicLeaderboard. Teams is shown only when teams is true or groupings is not empty. Journey, the running total each day with a line at each checkpoint, is shown only on a Leaderboard with checkpoints and a team goal. |
Leaderboard Item
| JSON Item | Data Type | Description |
|---|---|---|
| item | Leaderboard |
Leaderboard List
| JSON Item | Data Type | Description |
|---|---|---|
| own | Array of Leaderboard | List of the Leaderboards this user owns. |
| pending | Array of Leaderboard | List of the Leaderboards this user has not yet accepted. |
| accepted | Array of Leaderboard | List of the Leaderboards this user has accepted. |
Leaderboard User
| JSON Item | Data Type | Description |
|---|---|---|
| user | String | Add a single user |
| users | Array of String | Add a set of users. |
| teams | Any | The team of each participant, keyed by e-mail address, for a Leaderboard with teams. A team that is not yet one of the Leaderboard’s teamNames is added to them; an empty value removes the participant from their team. This may be sent with or without new users. |
| attributes | Any | The groupings of each participant beyond their team, keyed by e-mail address, each an object of grouping name to value, such as a region or a department. Values are merged into what the participant already has; an empty value removes the participant from that grouping and leaves their others. A grouping that is not yet one of the Leaderboard’s groupings is added to them. This may be sent with or without new users. |
Leaderboard Data
| JSON Item | Data Type | Description |
|---|---|---|
| data | Leaderboard Data Data |
Leaderboard User Preferences
| JSON Item | Data Type | Description |
|---|---|---|
| emailUpdate | Boolean | Whether this user receives the periodic e-mail summary for this Leaderboard. |
Leaderboard Data Data
| JSON Item | Data Type | Description |
|---|---|---|
| categories | Array of String | Categories of the chart, in increasing order |
| nestedGroups | Leaderboard Nested Groups | |
| checkpoints | Array of Leaderboard Data Checkpoint | The Leaderboard’s checkpoints in order from the start, each with when it was reached. Present only on a Leaderboard with checkpoints and a team goal. |
| total | Integer | How many participants the caller may see in all, of which entries is one page. |
| entries | Array of Leaderboard Data Data Entries | Participants, in ranking order |
Leaderboard Data Data Entries
| JSON Item | Data Type | Description |
|---|---|---|
| participant | String | Display name of the participant. |
| values | Array of Leaderboard Data Data Values | Values of the Participant |
Leaderboard Data Data Values
| JSON Item | Data Type | Description |
|---|---|---|
| category | String | Category name |
| value | Double | Category value |
Leaderboard Nested Groups
| JSON Item | Data Type | Description |
|---|---|---|
| levels | Array of String | The nesting levels anyone is in, outermost first, named as the Leaderboard’s nesting names them; an empty string is the team. |
| groups | Array of Leaderboard Nested Group | The groups of the outermost level, ranked against each other. |
Leaderboard Nested Group
| JSON Item | Data Type | Description |
|---|---|---|
| group | String | The group’s name. |
| rank | Integer | Its rank among the groups of its level within the same group above it. Absent when it is not ranked, because nobody in it has data. |
| value | Double | The group’s value by the board’s team rule. Absent when not ranked or when the organizer hid values. |
| members | Integer | Participants in this group. |
| withData | Integer | Members with data. |
| you | Boolean | True on the caller’s own group. Absent otherwise. |
| groups | Array of Leaderboard Nested Group | The groups of the next level within this one, ranked against each other. Absent at the innermost level. |
Leaderboard Checkpoint
| JSON Item | Data Type | Description |
|---|---|---|
| name | String | What the checkpoint is called. It must not be blank. |
| value | Double | The distance of the checkpoint from the start, in the unit of the Leaderboard’s primary Data Field, such as steps for STEPS or meters for DISTANCE_IN_METERS. |
| latitude | Double | Where the checkpoint is, used only to work out distances between checkpoints; it says nothing about any participant. Present only with longitude. |
| longitude | Double | Where the checkpoint is. Present only with latitude. |
Leaderboard Data Checkpoint
| JSON Item | Data Type | Description |
|---|---|---|
| name | String | What the checkpoint is called. |
| value | Double | The distance of the checkpoint from the start, in the unit of the Leaderboard’s primary Data Field. |
| latitude | Double | Where the checkpoint is, when the organizer gave it. |
| longitude | Double | Where the checkpoint is, when the organizer gave it. |
| reachedAt | String | The first day on which everyone’s running total reached this checkpoint, as yyyy-MM-dd. Absent until it has been reached. Each participant’s data is counted on their own day, in their own time zone, and the days are added together. It is worked out from the data each time, so data that arrives late or is deleted can move it. |
| teams | Array of Leaderboard Data Checkpoint Teams | On a Leaderboard where each team races the route (teamRace), when each team reached this checkpoint, the team furthest along first. Absent on any other Leaderboard. |
Leaderboard Data Checkpoint Teams
| JSON Item | Data Type | Description |
|---|---|---|
| name | String | The team. |
| reachedAt | String | The first day on which the team’s value, its members’ running total summed or averaged as teamSum says, reached this checkpoint, as yyyy-MM-dd. Absent until the team has reached it. |