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.
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"Request Parameters
None
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 |
|---|---|---|
| entries | Array of Object | The participants, in ranked order. |
Fields of entries
| JSON Item | Data Type | Description |
|---|---|---|
| participant | String | Display name of the participant. |
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/leaderboards/id/board/classic"Request Parameters
None
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. |
| 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. |
| 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. |
| 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. |
| display | Array of String | The representations shown for this Leaderboard, in display order. Each must be one of: Standings, Teams, Trend, Table. When present, it takes precedence over chartLineGranularity, chartTableGranularity and chartClassicLeaderboard. |
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 value that is not one of the Leaderboard’s teamNames, or is empty, removes the participant from their team. 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 |
| entries | Array of Leaderboard Data Data Entries | Participants |
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 |
