Dashboards API
FitnessSyncer’s core application has rich Dashboard capabilities. This API allows you to tap into that functionality; a key feature is that you can create chart requests without creating or managing FitnessSyncer Reports directly, and you can use your own visualization libraries.
Building a Chart can take time especially for users with lots of data and complex queries. To ensure that your request does not time out, this API is asynchronous. To get data for a dashboard, you must first create a dashboard request. Next, you must poll for the results using the Get Session API.
The best practice for creating reports is that you group similar requests for similar data types together. For example, if you are trying to fetch Steps and Distance information, grouping those together will be faster than making these separately.
The chart data is highly cacheable as the underlying data changes slowly. Please make reasonable caching decisions based on this.
When checking for results, you should insert a reasonable delay between polling attempts.
Note that dashboard results will automatically be removed after approximately 10 minutes.
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; during subsequent Get Session APIs, you must keep on requesting the desired format.
Create Dashboard Request
This creates a Dashboard Request which will provide you with an Session that you can then resolve to get to the actual data.
The data will be filtered based on the scopes provided; not all of the scopes listed are required.
Request Parameters
A body containing a Dashboard Request
Response
In some rare occasions, the data may already be available and may be returned immediately. If so, the HTTP Response Code will be a 200 and the body will be a Dashboard Data Response if the Accept header is not specified or is application/json OR a CSV if it is text/csv.
Typically, the HTTP Response Code will be a 202 the body will be a Dashboard Session Created.
Get Dashboard Session
After submitting a Create Dashboard Request, it will likely have responded with a 202 with a Dashboard Session Created.
If so, you must use the session id from that response to acquire the data using this API. This may require several calls before the data is available.
Note that dashboard results will automatically be removed after approximately 10 minutes.
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.
The data will be filtered based on the scopes provided; not all of the scopes listed are required.
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/dashboards/session_id"Request Parameters
None
Response
If the data is available, the HTTP Response Code will be a 200 and the body will be a Dashboard Data Response if the Accept header is not specified or is application/json OR a CSV if it is text/csv.
If the data is not available, the HTTP Response Code will be a 202 the body will be a Dashboard Session Created. The session id will not change between invocations.
If the session has expired, the HTTP Response Code will be a 410. You will need to recreate the Dashboard Request. If this happens repeatedly, please contact us.
Types
Dashboard Request
The Dashboard Request configures the chart the way you want it. To understand the parameters to the request, it is best to segment the parameters into how they are used.
- Data Selection Parameters
- dataView
- granularity
- dataFields
- includeNotebook
- sourceIds
- activityTypes
- customStart
- customEnd
- Processing Parameters
- removeDuplicates
- reducer
- finalReducer
- Chart Parameters
- treatNoDataAsZero
- treatZeroAsNoData
- labeler
| JSON Item | Data Type | Description |
|---|---|---|
| includeNotebook | Boolean | Should we include the values from FitnessSyncer Notebook? The default is true. |
| sourceIds | Array of String | This specifies the IDs of all of the sources to use for this query. If not specified, this will include all sources. |
| activityTypes | Array of Integer | This specifies the sport types you wish to include. If not specified, this will include all activities. See the Descriptions Activity API. |
| customStart | Long | If the DataView is set to PERIOD, this is the time in milliseconds to use as the start time in UTC. |
| customEnd | Long | If the DataView is set to PERIOD, this is the time in milliseconds to use as the end time in UTC. |
| removeDuplicates | Boolean | Should the chart remove duplicates? The default is true. |
| reducer | String | The reducer to run on the data per granularity. See the Descriptions API. The default is RANGE_NO_ZEROS. |
| finalReducer | String | The reducer to run on the data per period. See the Descriptions API. The default is RANGE_NO_ZEROS. |
| treatNoDataAsZero | Boolean | If there is no data available for a granularity, should it be treated as zero? The default is false. |
| treatZeroAsNoData | Boolean | If a value is 0, should it be treated as a null? The default is false. |
| dataView | String | View for the data. Must be one of: TEN_PERIODS, STANDARD, QUARTER, HALF, or YEAR. The default is STANDARD. |
| granularity | String | What is the granularity you wish for this to run at? Must be one of: DAY10 (10 periods), DAY, WEEK, MONTH, or PERIOD. If PERIOD, you must set customStart and customEnd. The default is DAY10. |
| labeler | String | What should we use for the labeler of the data? This allows you to group the data differently; the default is PROVIDER. See the Descriptions API. |
| dataFields | Array of String | Each of the DataFields for the fields to be returned. See the Descriptions API. This is a required field. |
Dashboard Session Created
| JSON Item | Data Type | Description |
|---|---|---|
| session | String | Session id to use with the Session API |
Dashboard Response
The Dashboard response is a set of series intended for a chart. Depending on the number of data fields, parameters you have selected (such as the Range reducer and data values), and other parameters, there could be more than one series.
In the case of Range reducers (RANGE, RANGE_NO_ZEROS, and SUMRANGE_NO_ZEROS) and where data has more than one value per period, the series will be duplicated and will contain the minimum (min), maximum (max), average (avg), sum, and number of entries (count) as separate series. You can identify this as the label will be duplicated and the type will indicate the meaning of the value.
Each series has a label and an array of values. The Categories root parameter correspond to the array indexes of these values.
| JSON Item | Data Type | Description |
|---|---|---|
| noData | Boolean | if this is true, there is no data associated with this request. |
| categories | Array of String | Categories of the chart, in increasing order |
| series | Array of Dashboard Data Series | Chart Data |
Dashboard Data Series
| JSON Item | Data Type | Description |
|---|---|---|
| label | String | Label of the Row. |
| values | Array of Dashboard Data Values | Values of the Series |
Dashboard Data Values
| JSON Item | Data Type | Description |
|---|---|---|
| label | String | Label for this series value. |
| type | String | When you are using a Range reducer and there is more than one value provided, the label will be duplicated and will have a series for each of the types. Must be one of: sum, min, max, avg, count |
| values | Array of Double | Category value for this series correlating to the category index in the global object. You will need to overlay the nulls array on this. |
| nulls | Array of Boolean | For any category value for this series which is null, there will be a true in this array. This array may not be present. |
