Table of Contents
- Introduction
- Authentication
- User Preferences
- Data Sources
- Data Source Items
- Destination Tasks
- Providers
- Sync Status
- FitnessSyncer Notebook
- Descriptions API
- Notifications
- Leaderboards
- Dashboards
- Data Types
- TaskType
- List of Source Data
- Source Data Item
- List of Source Data Items
- List of Sync Items
- Sync Item Item
- Source Data List Entry
- Source Item Links Item
- List of Task Type
- Id
- Historic Sync Request
- Source Data
- List of Destination Task
- Destination Task Item
- Destination Task Item
- Destination Task
- Sync Destination Task
- User Preferences
- List of Providers
- Provider
- Provider Authentication
- Provider Authentication Item
- Provider Authentication Key
- Sync Status
- Sync Status Results
- Subscription
- Notification
- Description Results
- Description
- Power Zones
- Leaderboard
- Leaderboard Item
- Leaderboard List
- Leaderboard User
- Leaderboard Data
- Leaderboard Data Data
- Leaderboard Data Data Entries
- Leaderboard Data Data Values
- Dashboard Request
- Dashboard Session Created
- Dashboard Response
- Dashboard Data Series
- Dashboard Data Values
- Errors
- Items
- Daily Summary Data
- Character Sets
- Language
- Compression
- Errors
- Future Proofing
- Developer Support
FitnessSyncer API
This document provides an overview of the FitnessSyncer API so that you may integrate the data in FitnessSyncer with your applications. Should you have any questions, encounter any issues, or need a different interface, please contact us.
By using our API, you agree with our Terms of Use available on our site.
We will periodically make changes to this API. Changes will generally be additive, however, periodically, we may create breaking changes and will attempt to notify you with sufficient time to update your implementations. Please contact us to ensure that you are on this mailing list.
You can also use the FitnessSyncer OpenAPI Specification to generate code, although this documentation should be used. We also have a few generated and tested implementations if needed; please contact us to get access..
Introduction
FitnessSyncer’s API provides access to information health and fitness data from over 50 sources as is displayed within the FitnessSyncer Stream and FitnessSyncer Dashboard, including data sources such as Fitbit and data captured in FitnessSyncer Notebook.
The first step in integrating with the FitnessSyncer API is to authenticate. Authentication is done via the OAuth protocol and once the user grants permission to your application to access their information, FitnessSyncer will provide you with a token that you can use for your requests.
Once authenticated, your application can then access any data in FitnessSyncer or upload data into FitnessSyncer.
Most applications will interact with a Source, which is a feed from one data provider for a type of data. A Data Provider is the application or hardware that provides data and data-types such as Activity Tracking, Exercise, Allergies, Weight, Blood Pressure, Cholesterol, Condition, Glucose, Medications, Nutrition, Oxygen, Sleep, and Temperature data.
For example, if a user has a Fitbit device from which they track Exercise and Sleep information, this will result in two Sources, one for the Exercise from Fitbit, and the other for Sleep Information from Fitbit.
FitnessSyncer also provides Destination Tasks. Destination Tasks complete operations such as synchronize the data into other services, provide e-mail notification, automatically refresh sources on a schedule, etc. These are also available within this API.
When FitnessSyncer has new data, consumers of our API will need to read that new data in. A subscription allows a webhook to be sent to you when there is new data. If you wish to use this, please contact us.
FitnessSyncer free accounts are limited to the number of sources and destinations they may create. Please contact us if this is an issue.
Authentication
The FitnessSyncer API uses OAuth2 for authentication. This is a standard authentication scheme that is well documented on the web; this documentation will provide you an overview of what you need to do.
Personal Applications can be created in our developer console. For other use-cases, please contact us and we will provide you with the following information:
- Client ID
- Client Secret
- Redirect URL
Note that the Redirect URL is case sensitive and should be SSL-based as our browser policy is to not redirect to non-SSL enabled locations.
Authenticating
To authenticate a web-application, the basic workflow is as follows:
- Redirect the user to FitnessSyncer to authorize your application’s access to their data.
- Once approved, FitnessSyncer will redirect the user back to your site with a temporary token.
- With the temporary token, you need to acquire the Access and Refresh Tokens.
To start the authentication workflow, you will need to redirect the user to https://www.fitnesssyncer.com/api/oauth/authorize with following query string parameters:
| Query String Parameter Name | Description |
|---|---|
| response_type | Set to “code” |
| client_id | Set to your Client Id. |
| redirect_uri | Set to your Redirect URL |
| scope | Currently set to “sources” |
| state | Set to any state you wish to get returned on the redirect URL. |
Here is an example URL:
On success, this will redirect back to your site with the following query string parameters:
| Redirect Query String Parameter Name | Description |
|---|---|
| code | A temporary Access Code. The code will be set to “error” if there was an error granting the permission. |
| state | The same value you passed in the above state, if any. |
Once you have the code, you can access the code by making a POST request to https://api.fitnesssyncer.com/api/oauth/access_token. The body of this request should contain:
| POST Parameter Name | Description |
|---|---|
| grant_type | Set to “authorization_code” |
| code | The temporary code received. |
| client_id | Set to your Client Id. |
| client_secret | Set to your Client Secret. |
| redirect_uri | Set to your Redirect URL |
Upon success, you will receive a 200-response code with a JSON Body as follows:
| Key | Description |
|---|---|
| expires_in | Time in seconds since the epoch when the token expires. |
| access_token | Token to access the data. |
| refresh_token | A token to get a new access_token when the token expires. |
To access any resources from this point forward, simply include the Authorization header with the value “Bearer ” followed by the access_token above. For example, if the access_token was “asdfasdf”, the Authorization header would be set to “Bearer asdfasdf”.
Refreshing the token
The access token will expire periodically. You may either keep track of the expiration yourself or when you make a request, a 401-status code is returned and you will need to reauthenticate. You can renew the token by making a POST request to: https://api.fitnesssyncer.com/api/oauth/access_token. The body of this request should contain:
| POST Parameter Name | Description |
|---|---|
| grant_type | Set to “refresh_token” |
| refresh_token | Set to the refresh_token as received above. |
| client_id | Set to your Client Id. |
| client_secret | Set to your Client Secret. |
| redirect_uri | Set to your Redirect URL as included in the original request |
Upon success, you will receive a 200-response code with a JSON Body as follows:
| Key | Description |
|---|---|
| expires_in | Time in seconds when the token expires in. |
| access_token | Token to access the data. |
| refresh_token | A token to get a new access_token when the token expires. |
Revoking the token
You may revoke a token at any time by making a POST request to: https://api.fitnesssyncer.com/api/oauth/revoke_token. The header would be the Authorization header as defined above.
Verb
POST
Resource
https://api.fitnesssyncer.com/api/oauth/revoke_token
Request Parameters
None
Response
On success, a 200 will be returned with a JSON object indicating the successful status.
Creating users
If your application can create new users, you can do so using this API.
To do so, a POST request to https://api.fitnesssyncer.com/api/oauth/access_token. The body of this request should contain:
| POST Parameter Name | Description |
|---|---|
| grant_type | Set to “password” |
| create | Set to “true” |
| username | The new user’s username. This must be in the form of an e-mail address. |
| password | The new user’s password |
| client_id | Set to your Client Id. |
| client_secret | Set to your Client Secret. |
| redirect_uri | Set to your Redirect URL |
Upon success, you will receive a 200-response code with a JSON Body as follows:
| Key | Description |
|---|---|
| expires_in | Time in seconds when the token expires in. |
| access_token | Token to access the data. |
| refresh_token | A token to get a new access_token when the token expires. |
To access any resources from this point forward, simply include the Authorization header with the value “Bearer ” followed by the access_token above. For example, if the access_token was “asdfasdf”, the Authorization header would be set to “Bearer asdfasdf”.
Other Considerations
It is important to realize that a user can also revoke an access token. For example, under the Permissions tab of My Account, they may choose to revoke your permissions entirely. When this occurs, accessing and refreshing the token will fail with a 403 and you will need to reauthenticate from the beginning.
User Preferences
Reading user preferences
You may read the user’s preferences by using this API. This is for informational purposes only. None of the actual API requires your knowledge of these preferences.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/users/preferences
Request Parameters
None
Response
The response will be a 200 with a JSON body with the User Preferences.
Example JSON
"heightInMeters": 0,
"canemail": false,
"autosync": true,
"bmr": 0,
"timezone": "UTC",
"weightMetric": false,
"heartRateAge": 30,
"internationaltime": false,
"timezoneDisplayName": "Coordinated Universal Time",
"waterML": false,
"distanceOverSteps": false,
"temperatureCelsius": false,
"heartRateMax": 187,
"pro": true,
"glucoseMetric": false,
"displayname": "",
"heartRateLevel4": 149,
"heartRateLevel5": 168,
"heartRateLevel2": 112,
"distanceMetric": false,
"privateActivities": false,
"heartRateLevel3": 130,
"heartRateLevel1": 74,
"weekStartsOnMonday": false
}
Updating user preferences
You may update the user’s preferences by using this API.
Verb
POST
Resource
https://api.fitnesssyncer.com/api/users/preferences
Request Parameters
The Request Body will be a JSON object with the changes of the User Preferences.
Response
The response will be a 200 with a JSON body with the User Preferences.
Data Sources
A Data Source is a feed of data that comes from a particular provider for a specific type of data.
Listing Data Sources
To learn the data sources that exist or to find the id of your desired data type, you will need to issue a list.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/providers/sources/
Request Parameters
None
Response
The response will be a 200 with a JSON body that will the List Source Data. See the Data Types section for a description.
Example JSON
"name": "My Health Data",
"id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
"type": "Activity",
"enabled": true,
"providerType": "EpsonPulseSense"
}]}
Notes
The above will not contain entries from the FitnessSyncer Notebook. You must query for those separately.
If enabled and permission is granted by the participant, Researchers and Corporate Wellness can acquire the full list data sources from all participants using this API.
Get a Specific Source
If you have an id to a specific source item, you can easily acquire the configuration of that item easily.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/providers/sources/id
Request Parameters
None
Response
The response will be a 200 with a JSON body that will contain a Source Data Item. See the Data Types section for a description.
Example JSON
"name": "My Health Data",
"id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
"type": "Activity",
"enabled": true,
"providerType": "EpsonPulseSense"
}}
If enabled and permission is granted by the participant, Researchers and Corporate Wellness can acquire a specific participant’s data source.
Creating new Data Sources
To create a new Data Source, one must issue a PUT request with that configuration.
Please see Provider Authentication to configure authentication for your source.
The user can also change this item using our editor. It is recommended that you only cache this data temporarily.
Verb
PUT
Resource
https://api.fitnesssyncer.com/api/providers/sources/
Request Parameters
The Request Body will be a JSON object with the Source Data. See the Data Types section for that definition. The id in that Source Data will be ignored.
Response
The Response will be a JSON body with an id field indicating the ID of the new item.
Updating Data Sources
To update a Data Source, one must issue a POST request with that configuration.
Please see Provider Authentication to configure authentication for your source.
Verb
POST
Resource
https://api.fitnesssyncer.com/api/providers/sources/id
Request Parameters
The Request Body will be a JSON object with the Source Data. See the Data Types section for that definition. The id in that Source Data will be ignored.
Response
The Response will be a JSON body with an id field indicating the ID of the updated item.
Deleting Data Sources
When you are finished with a data source, simply delete it. This operation cannot be undone.
Verb
DELETE
Resource
https://api.fitnesssyncer.com/api/providers/sources/id
Request Parameters
None
Response
The Response will be a JSON body with an id field indicating the ID of the deleted item.
Refreshing Data Sources
FitnessSyncer will periodically refresh data sources. If your application wishes to ensure that you have the latest data available, you can request a refresh.
When this operation completes, the task is enqueued and will execute sometime in the near future. You may check on the status of the task via the Sync Status API.
Note: This is only available on certain accounts. Please contact us if you require it.
Verb
POST
Resource
https://api.fitnesssyncer.com/api/providers/sources/id/refresh
Request Parameters
None are required.
If the user is a FitnessSyncer Pro, you may issue a Historic Sync request.
Response
On success, this will return a 202 with a JSON body indicating the id of the item enqueued.
In the event that there is already a pending request for this user, a 409 will be returned to you.
Data Source Items
With the identifier for a Data Source, you can access the data associated with the item.
Listing Items
The Listing API is a paging-based API, with the first page being the most recent.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/providers/sources/id/items/
Request Parameters
| Query Parameter Name | Description |
|---|---|
| offset | How many entries should we skip? Default is 0. |
| limit | How many entries would you like to return? Default and max is 100. |
Response
The Response will be a JSON body with an items field containing a List Source Data.
If enabled and permission is granted by the participant, Researchers and Corporate Wellness can acquire a specific participant’s data listing.
Getting a Specific Item
With the identifier for a Data Source, you can then access the data associated with the item. Items are generally static, so you may cache them in accordance to our terms of use.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/providers/sources/id/items/itemId
Request Parameters
None
Response
The Response will be a JSON body with a SyncItem Item. See the Data Types section for a definition.
If enabled and permission is granted by the participant, Researchers and Corporate Wellness can acquire a specific participant’s activity item.
Creating new Items
This will allow you to insert new items into FitnessSyncer. You should upload data in reverse date order. It should be noted that inserting an item older than the most current item might not synchronize that item for destinations. This operation can only be done for items for which you have permission to do so.
Verb
PUT
Resource
https://api.fitnesssyncer.com/api/providers/sources/id/items/
Request Parameters
Body would be the JSON Serialization of the Item to be inserted. See the Data Types section for details.
Response
The Response will be a JSON body with an id field containing the new id. If the source has a filter associated with it which filters this out, the returned id will be “-FILTERED-”.
Updating Items
You may update any item that you have created. It should be noted that updating older items might not properly update the fields for already synchronized items. This operation can only be done for items for which you have permission to do so.
Verb
POST
Resource
https://api.fitnesssyncer.com/api/providers/sources/id/items/itemId
Request Parameters
Body would be the JSON Serialization of the Item to put inserted. See the Data Types section for details.
Response
The Response will be a JSON body with an id field containing the new id. If the source has a filter associated with it which filters this out, the returned id will be “-FILTERED-”.
Uploading Fitness Files
If you have the data already within a file, you can upload that file into the system.
This API is just for uploading that file. To change any metadata, you will need to update that record accordingly.
Note that a single upload may result in multiple items depending on the file format.
Verb
POST
Resource
https://api.fitnesssyncer.com/api/providers/sources/id/items/upload
Request Parameters
The Body is a multipart-form that contains an element named as file which encompasses a TCX, GPX, KML, KMZ, FIT, or PWX file. This must also include the standard Content-Disposition header.
By default, FitnessSyncer will attempt to de-dupe uploads. If you wish to circumvent this, please include the dedupe=false query string parameter.
If you are attempting to upload a file for a specific item, you may also include the id={id} query string parameter.
Response
The Response will be a JSON body with a list of items; each item will include an id and url for the item.
Deleting Items
Verb
DELETE
Resource
https://api.fitnesssyncer.com/api/providers/sources/id/items/itemId
Request Parameters
None
Response
The Response will be a JSON body with an id field containing the deleted item.
Destination Tasks
A Destination Tasks is a task that operates over the source data to accomplish a task. The most common of these is a data synchronization task.
Listing Destination Tasks
To learn the destinations tasks that exist or to find the id of your desired destination, you will need to issue a list.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/providers/destinations/
Request Parameters
None
Response
The response will be a 200 with a JSON body that will contain a List of Destination Tasks. See the Data Types section for a description.
Example JSON
"taskType": "Activity",
"hour": -1,
"name": "Synchronization Task",
"id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
"type": "sync",
"enabled": true,
"providerType": "FitBit"
}]}
Get a Specific Destination Task
If you have an id to a specific destination task, you can easily acquire the configuration of that task easily.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/providers/destinations/id
Request Parameters
None
Response
The response will be a 200 with a JSON body that will contain an Item Destination Task. See the Data Types section for a description.
Example JSON
"taskType": "Activity",
"hour": -1,
"name": "Synchronization Task",
"id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
"type": "sync",
"enabled": true,
"providerType": "FitBit"
}}
Creating new Destinations Task
To create a new Destination Task, one must issue a PUT request with that configuration.
Please see Provider Authentication to configure authentication for your destination.
The user can also change this item using our editor. It is recommended that you only cache this data temporarily.
Verb
PUT
Resource
https://api.fitnesssyncer.com/api/providers/destinations/
Request Parameters
The Request Body will be a JSON object with the Destination Data. See the Data Types section for that definition. The id in that Destination Data will be ignored.
Response
The Response will be a JSON body with an id field indicating the ID of the new item.
Updating Destinations Tasks
To update a Destination Task, one must issue a POST request with that configuration.
Please see Provider Authentication to configure authentication for your destination.
Verb
POST
Resource
https://api.fitnesssyncer.com/api/providers/destinations/id
Request Parameters
The Request Body will be a JSON object with the Destination Data. See the Data Types section for that definition. The id in that Destination Task will be ignored.
Response
The Response will be a JSON body with an id field indicating the ID of the updated item.
Deleting Data Destinations
When you are finished with a destination task, simply delete it. This operation cannot be undone.
Verb
DELETE
Resource
https://api.fitnesssyncer.com/api/providers/destinations/id
Request Parameters
None
Response
The Response will be a JSON body with an id field indicating the ID of the deleted item.
Executing Data Destinations
FitnessSyncer will periodically execute destinations tasks. If your application wishes to run these themselves, you can request an execute.
When this operation completes, the task is enqueued and will execute sometime in the near future. You may check on the status of the task via the Sync Status API.
Note: This is only available on certain accounts. Please contact us if you require it.
Verb
POST
Resource
https://api.fitnesssyncer.com/api/providers/destinations/id/execute
Request Parameters
None
Response
On success, this will return a 200 with a JSON body indicating the id of the item enqueued.
In the event that there is already a pending request for this user, a 409 will be returned to you.
Providers
To configure a source or destination, you will require some information regarding our current providers and authenticating with them. The following documentation outlines this.
Listing Providers
This method acquires the data providers that are presently available on FitnessSyncer. It should be noted that this method is highly cacheable, especially if you are using a fixed set of providers.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/providers/types/
Request Parameters
None
Response
The Response will be a JSON body with Provider List.
Provider Authentication
There are various ways to configure authentication for a provider. The provider list would have provided you with a value for authenticating.
| Name | Description |
|---|---|
| UsernamePassword | This indicates that you must provide a username and password for this user. |
| Identifier | This indicates that you must provide an identifier for this user for authentication. |
| AppRequired | This indicates that one of our or a partner app is required to authenticate. If it is a supported app, an appurl will be also included in the body. |
| OAuth | This indicates that you must request an OAuth token flow to be initiated for your user to provide FitnessSyncer with the appropriate authentication. |
| Unsupported | This should not generally be returned, but should it be returned, you should ignore such providers. |
Once you have selected a provider and created a source for it, you need to add authentication for it as follows.
You should build your application such that if there are new values, that your application appropriate degrades.
Verb
PUT
Resource
https://api.fitnesssyncer.com/api/providers/sources/id/authentication
https://api.fitnesssyncer.com/api/providers/destinations/id/authentication
Where id is the id of the Source you are trying to authenticate.
Request Parameters
The request body will contain a JSON object as described here.
UsernamePassword
This will securely store the authentication on our servers and return a 200 response to you on success.
| Key | Description |
|---|---|
| type | Always UsernamePassword |
| username | The username required for the user’s authentication |
| password | The password required for the user’s authentication |
UsernamePasswordKey
This will securely store the authentication on our servers and return a 200 response to you on success.
| Key | Description |
|---|---|
| type | Always UsernamePasswordKey |
| username | The username required for the user’s authentication |
| password | The password required for the user’s authentication |
| clientId | The client id required for the user’s authentication |
| clientSecret | The client secret required for the user’s authentication |
Identifier
This will securely store the identifier for the service on our servers and return a 200 response to you on success.
| Key | Description |
|---|---|
| type | Always Identifier |
| identifier | The identifier required for the user’s authentication |
OAuth
This will start the redirects required to authenticate an OAuth-like scheme. This will return a 202 to you with a Location header to pass onto your user. Your user will end at the URL provided below on success or failure (except where beyond our control or extreme failures).
| Key | Description |
|---|---|
| type | Always OAuth |
| redirect | The URL you wish for FitnessSyncer to redirect the user for either success or failure modes |
OAuthReuse
See Provider Authenticate for how to get the id field for this request.
This will store the re-use request and will return a 200 response to you on success.
| Key | Description |
|---|---|
| type | Always OAuthReuse |
| id | id of the item which you wish to re-use the authentication of |
Response
If your request has been stored successfully, the response code will be a 200 without a body.
If your request has been initiated successfully, the response code will be a 202. Such a request will contain a Location header that you must send your user to. That location will be directed back to a FitnessSyncer service that will drive the completion of the request and redirect the user back to your site when the request is successful or has failed.
Existing Provider Authentication
If you are using the same source system for multiple devices, you need to use the same authentication for each source. This method will allow you to acquire the authorization summary of what exists already so that you can re-use that authentication.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/providers/authentication/
Request Parameters
None
Response
The Response will be a JSON body with a Providers Authentication.
Example JSON
"keys": [{
"name": "Fitbit Sleep Source",
"id": "d8e1eb2e-bf26-4521-8c4b-7d85590e0588"
}],
"name": "Fitbit",
"type": "FitBit"
}]}
Synchronization Status
The Source Refresh or Destination Task Execute APIs, you are not given any updates on what the status of those tasks is. This API provides you some insight.
Getting Synchronization Status
If you are using the same source system for multiple devices, you need to use the same authentication for each source. This method will allow you to acquire the authorization summary of what exists already so that you can re-use that authentication.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/syncs/
Request Parameters
None
Response
The Response will be a JSON body with a Sync Status result.
FitnessSyncer Notebook
The FitnessSyncer Notebook uses the same API as the Data Source Items; however, the id is the constant “notebook”.
This section describes the new functionality for the API.
Listing Items by Type
Verb
GET
Resource
https://api.fitnesssyncer.com/api/providers/sources/notebook/itemsByType/type
where type is one of the TaskType’s
Request Parameters
| Query Parameter Name | Description |
|---|---|
| offset | How many entries should we skip? Default is 0. |
| limit | How many entries would you like to return? Default and max is 100. |
Response
The Response will be a JSON body with an items field containing a List Sync Items.
Getting Categories
The FitnessSyncer Notebook can have various task types. This API will tell you which TaskTypes are being used.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/providers/sources/notebook/categories
Request Parameters
None
Response
The Response will be a JSON body with an items field containing a List Task Types.
Notifications
You may subscribe your users to get notifications for certain classes of errors or new items to be sent directly to your site via WebHook or collected periodically.
For webhooks, the basic workflow for this is that you would provide us with a URL to be notified and potentially a filter. You can choose to be notified with each item or as a generic notification. Your site must use SSL using a non-self-served certificate. You should not whitelist our IP addresses as we updated our addresses regularly for scalability reasons. Each message sent to you will contain a X-FitnessSyncer-Signature header which will be the HMAC-SHA1 hash of the context body part using your OAuth2 Secret Key as the signature.
To pull notifications, the basic workflow for this is that you would provide with maybe a filter and then periodically you will collect the notifications and delete any claims.
Once notifications are enabled for your account, then you can subscribe a user using the API below. When the user adds a new item, this item would be sent or made available to your notification system.
If your account has multiple notification rules, you only need to subscribe once per user.
The request to your server will be a POST request containing:
| POST Parameter Name | Description |
|---|---|
| context | A JSON Object containing at a minimum the notificationKey from below. |
| file | For non-generic pushes, this would contain the GPX/TCX/FIT/PWX/KML/KMZ/etc. file. |
| sourceId | For non-generic pushes, this would be the id of the SourceData that generated this item. |
| itemId | For non-generic objects, this would be the item id. |
Your server must respond with a 200 or 201. If your server responds with a 403, the user will be automatically unsubscribed. All other error codes will be retried up-to a predefined maximum attempts.
Learning if there is a subscription
To figure out if there is an active subscription, use this method. You may periodically wish to do this in the event of errors notifying your service of a subscription.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/subscriptions/
Request Parameters
None
Response
The response to this query will be a JSON object with Subscription.
If there is not an active subscription, the response will be a 404.
Sample
Subscribing
To subscribe a user for notifications, you can use this API.
Verb
PUT
Resource
https://api.fitnesssyncer.com/api/subscriptions/
Request Parameters
None
Response
The response to this query will be a JSON object with Subscription.
Sample
Unsubscribing
To unsubscribe from the API, use this API.
Note that if your server responds with a 403 error when it is notified, they will be automatically unsubscribed.
Verb
DELETE
Resource
https://api.fitnesssyncer.com/api/subscriptions/notificationKey
Request Parameters
None
Response
The response to this query will be a JSON object with a status indicating success.
Sample
Pull Notifications: Claiming
For pull notifications, you will need to claim notifications, process the notifications, and then delete the claim. If you do not delete the claim, the notification will eventually come back to you.
Note that we will only provide you with a maximum of 100 notifications per response. If you have more than 100 notifications, you will need to requery the API for each notification.
Verb
POST
Resource
https://api.fitnesssyncer.com/api/notifications/
Request Parameters
None
Response
The body of the JSON object will have Notification result.
Sample
"claim": "1bd2a05e-7c1e-40fc-b3de-57f0b1672861",
"notifications": {
"items": [{"notificationKey": "1bd2a05e-7c1e-40fc-b3de-57f0b1672861"}],
"errors": []
}
}
Pull Notifications: Deleting Notifications
Once you have successfully process a notification, you must delete the notification. Failure you to do so will result in the same notifications being processed by you multiple times.
Verb
DELETE
Resource
https://api.fitnesssyncer.com/api/notifications/claim
Request Parameters
None
Response
The response to this query will be a JSON object with a status indicating success.
Sample
Descriptions API
For data values which contain a key and a value descriptor, the Descriptions API provides a convenient way to resolve those two values. This API is highly cacheable.
Getting Descriptions
This method acquires the metadata from FitnessSyncer. This is highly cacheable.
Verb
GET
Resource
https://api.fitnesssyncer.com/api/descriptions/type
where type is one of activities, comparisons, dataFields, granularities, or reducers.
| Key Parameter Name | Description |
|---|---|
| activities | List of Activity Types that FitnessSyncer Supports. |
| comparisons | List of Comparisons Types that FitnessSyncer Supports for Filters, Leaderboards, ShoeRenew, and other operations. |
| dataFields | List of Data Fields that FitnessSyncer Supports for Reports |
| granularities | List of Granularities that FitnessSyncer Supports for Reports |
| labelers | List of Labelers that FitnessSyncer Supports for Reports |
| reducers | List of Reduces that FitnessSyncer Supports for Filters, ShoeRenew, and other operations |
| timezones | List of Time Zones that FitnessSyncer Supports |
| JSON Item | Data Type | Description |
|---|---|---|
| items | Array of SourceData |
Source Data Item
| JSON Item | Data Type | Description |
|---|---|---|
| item | SourceData |
List of Source Data Items
| JSON Item | Data Type | Description |
|---|---|---|
| items | Array of SyncItemListItem |
List of Sync Items
| JSON Item | Data Type | Description |
|---|---|---|
| items | Array of SyncItem |
Sync Item Item
| JSON Item | Data Type | Description |
|---|---|---|
| item | SyncItem |
Source Data List Entry
| JSON Item | Data Type | Description |
|---|---|---|
| itemId | String | Id of the Item |
| date | Long | Time of the item as milliseconds since the Epoch in UTC |
| links | SyncItemLinks |
Source Item Links Item
| JSON Item | Data Type | Description |
|---|---|---|
| fit | String | URL for the FIT file (if applicable) |
| pwx | String | URL for the PWX file (if applicable) |
| tcx | String | URL for the TCX file (if applicable) |
| kml | String | URL for the KML file (if applicable) |
| kmz | String | URL for the KMZ file (if applicable) |
| csv | String | URL for the CSV file (if applicable) |
| gpx | String | URL for the GPX file (if applicable) |
List of Task Type
| JSON Item | Data Type | Description |
|---|---|---|
| items | Array of String | List of the TaskTypes. One of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
Id
| JSON Item | Data Type | Description |
|---|---|---|
| id | String | Identifier of the item created or changed. |
Historic Sync Request
This is an optional request body to the Refresh Data Source.
| JSON Item | Data Type | Description |
|---|---|---|
| start | Long | Start time for the Historic Sync in milliseconds since the Epoch in UTC |
| end | Long | End time for the Historic Sync in milliseconds since the Epoch in UTC |
| Boolean | True to e-mail the user at the end of the historic sync. |
Source Data
This structure defines the Source Data
| JSON Item | Data Type | Description |
|---|---|---|
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
| id | String | A String identifier for the task. This is used throughout the API for uniquely identifying this item. |
| name | String | A user description for the source. |
| context | String | Optional and only available in Pro accounts, provides a grouping context for our charts. |
| providerType | String | The Provider Type enumeration value. |
| enabled | Boolean | Indicates whether this source is enabled or not. |
| deprecated | Boolean | True if this item has been deprecated. |
| ignoreDailyCalories | Boolean | True to ignore the daily calories summary |
| lastError | String | This is a description of the last error that this source encountered. |
| date | Long | Date of the last synchronization or error. |
| identifier | String | If the authentication for this is a username or identifier, this would be that string to aid in editing. |
At this time, filters are not configurable via the API. Other fields may be included in the future and should be ignored.
Sample
"name": "My Health Data",
"id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
"type": "Activity",
"enabled": true,
"providerType": "EpsonPulseSense"
}
List of Destination Task
| JSON Item | Data Type | Description |
|---|---|---|
| items | Array of DestinationTask |
Destination Task Item
| JSON Item | Data Type | Description |
|---|---|---|
| item | DestinationTask |
Destination Task
This structure defines the Destination Task, which based on the type of task will extend this task to other types.
| JSON Item | Data Type | Description |
|---|---|---|
| type | String | This is the type of destination task. Not all of the types supported by FitnessSyncer are documented here. |
| id | String | A String identifier for the task. This is used throughout the API for uniquely identifying this item. |
| name | String | A user description for the destination. |
| hour | Integer | Hour for this task to be ran (if Pro). The time is specified in PST. |
| localHour | Integer | Hour converted to the user's timezone (from their profile). |
| lastError | String | This is a description of the last error that this source encountered. |
| date | Long | Date of the last synchronization or error. |
| enabled | Boolean | Indicates whether this destination is enabled or not. |
At this time, filters are not configurable via the API. Other fields may be included in the future and should be ignored.
If you require access to one of the destination tasks which are not documented, simply contact us.
Sample
"taskType": "Activity",
"hour": -1,
"name": "Synchronization Task",
"id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
"type": "sync",
"enabled": true,
"providerType": "FitBit"
}
Sync Destination Task
This structure defines the Destination Task of type “sync”. This extends Destination Task.
| JSON Item | Data Type | Description |
|---|---|---|
| taskType | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
| providerType | String | The Provider Type enumeration value. See Listing Providers for details. |
| skipDataFields | Array of String | List of fields to skip over (if applicable) |
| onlyIfNotOnDest | Boolean | Mode that only places items on the destination IF there is nothing on the destination for the day. Not recommended. |
| identifier | String | If the authentication for this is a username or identifier, this would be that string to aid in editing. |
| type | String | This is the type of destination task. Not all of the types supported by FitnessSyncer are documented here. |
| id | String | A String identifier for the task. This is used throughout the API for uniquely identifying this item. |
| name | String | A user description for the destination. |
| hour | Integer | Hour for this task to be ran (if Pro). The time is specified in PST. |
| localHour | Integer | Hour converted to the user's timezone (from their profile). |
| lastError | String | This is a description of the last error that this source encountered. |
| date | Long | Date of the last synchronization or error. |
| enabled | Boolean | Indicates whether this destination is enabled or not. |
Sample
"taskType": "Activity",
"hour": -1,
"name": "Synchronization Task",
"id": "1d4c35b9-f006-4f34-acea-2af7bc25161a",
"type": "sync",
"enabled": true,
"providerType": "FitBit"
}
User Preferences
| JSON Item | Data Type | Description |
|---|---|---|
| autosync | Boolean | If this is a Pro user, this will denote whether Auto-Sync is enabled or not. |
| bmr | Integer | Basal Metabolic Rate. If unknown, this will be 0. |
| birthdate | Long | Birth date as an epoch of the user. This will be 0 if unknown. |
| age | Integer | Age of the user. This will be 0 if unknown. |
| canemail | Boolean | True if FitnessSyncer can periodically send e-mails to this user. |
| distanceOverSteps | Boolean | For destination syncs, does the user prefer distance or steps to be synchronized? |
| privateActivities | Boolean | Indicates whether the user prefers private activities for destination synchronizations? |
| heightInMeters | Double | How tall is the user in meters? If unknown, this will be 0. |
| distanceMetric | Boolean | Indicates whether the user prefers metric units for distance and height. |
| nutritionMetric | Boolean | Indicates whether the user prefers metric units for nutrition. |
| weightMetric | Boolean | Indicates whether the user prefers metric units for weight. |
| glucoseMetric | Boolean | Indicates whether the user prefers metric units for blood-based units. |
| temperatureCelsius | Boolean | Indicates whether the user prefers metric units for temperature. |
| waterML | Boolean | Indicates whether the user prefers metric units for water consumption. |
| internationaltime | Boolean | Indicates whether the user prefers 24-hour time and YYYY-MM-DD dates or not. |
| weekStartsOnMonday | Boolean | Indicates whether the user prefers the week to start on Monday instead of Sunday. |
| locale | String | Locale of the user. |
| numericLocale | String | User's number locale, currently en or fr. |
| bodyshape | String | Body Shape of the user. Must be one of: Unspecified, Rectangle, Triangle, Trapezoid, Oval, HourGlass, Round, InvertedTriangle |
| sex | String | Gender of the user. Must be one of: Unspecified, Female, Male |
| timezone | String | User’s time zone. |
| timezoneDisplayName | String | Time Zone display Name. |
| displayname | String | User’s Display Name. |
| heartRateLevel1 | Integer | User’s minimum heart rate at level 1 or the system default. |
| heartRateLevel2 | Integer | User’s minimum heart rate at level 2 or the system default. |
| heartRateLevel3 | Integer | User’s minimum heart rate at level 3 or the system default. |
| heartRateLevel4 | Integer | User’s minimum heart rate at level 4 or the system default. |
| heartRateLevel5 | Integer | User’s minimum heart rate at level 5 or the system default. |
| heartRateAge | Integer | User’s age last used to calculate the heart rate. |
| heartRateMax | Integer | User’s maximum heart rate or the system default. |
| pro | Boolean | True if the user is a FitnessSyncer Pro subscriber |
| beta | Boolean | True if the user has any boolean flags. |
| powerZones | Map of String to PowerZones | List of Power Zone Definitions based on Sport. |
| sleepRatio | Double | Sleep Ratio for Sleep Debt Calculation. Defaults to 0.5 which represents 1:2 ratio (8 hours of sleep to 16 hours awake) |
| graphSleepByWakeTime | Boolean | How should the system graph sleep? If true, this will graph it based on the awake time. Otherwise, this will be graphed based on bedtime. |
List of Providers
| JSON Item | Data Type | Description |
|---|---|---|
| providers | Array of Provider |
Provider
| JSON Item | Data Type | Description |
|---|---|---|
| providerType | String | This is the value of the providerType to be passed in. This should not be displayed. |
| name | String | This is the description of the provider for display purposes. |
| authentication | String | This is the type of authentication which this provider requires. See the Provider Authentication section for information. |
| beta | Boolean | If this is true, this implies that this provider type is presently in public beta testing. |
| notifications | Boolean | True if this service currently does notifications-based synchronization. |
| cloudStorageMapsProvider | Boolean | True if this is a Cloud Storage Map Provider. |
| cloudStorageCsvProvider | Boolean | True if this is a Cloudd Storage CSV Provider. |
| googleServices | Boolean | True if this is part of the Google Authentication Service Suite |
| reauthenticateAll | Boolean | True if this is a candidate for Reauthenticate All. |
| historicSync | Boolean | True if this type supports Historic Sync. |
| compatibleAuthentication | Array of String | List of providers |
| faq | String | URL to the FAQ |
| logo | String | URL to the Logo |
| appurl | String | If this represents an app, this represents the URL for that app. |
| ActivityRead | Boolean | True if this provider can read activity data. |
| ActivityWrite | Boolean | True if this provider can write activity data. |
| AllergyRead | Boolean | True if this provider can read allergy data. |
| AllergyWrite | Boolean | True if this provider can write allergy data. |
| WeightRead | Boolean | True if this provider can read body composition data. |
| WeightWrite | Boolean | True if this provider can write body composition data. |
| BloodPressureRead | Boolean | True if this provider can read blood pressure data. |
| BloodPressureWrite | Boolean | True if this provider can write blood pressure data. |
| CholesterolRead | Boolean | True if this provider can read cholesterol data. |
| CholesterolWrite | Boolean | True if this provider can write cholesterol data. |
| ConditionRead | Boolean | True if this provider can read condition data. |
| ConditionWrite | Boolean | True if this provider can write condition data. |
| GlucoseRead | Boolean | True if this provider can read glucose data. |
| GlucoseWrite | Boolean | True if this provider can write glucose data. |
| MedicationRead | Boolean | True if this provider can read medication data. |
| MedicationWrite | Boolean | True if this provider can write medication data. |
| NutritionRead | Boolean | True if this provider can read nutrition data. |
| NutritionWrite | Boolean | True if this provider can write nutrition data. |
| OxygenRead | Boolean | True if this provider can read oxygen data. |
| OxygenWrite | Boolean | True if this provider can write oxygen data. |
| SleepRead | Boolean | True if this provider can read sleep data. |
| SleepWrite | Boolean | True if this provider can write sleep data. |
| TemperatureRead | Boolean | True if this provider can read temperature data. |
| TemperatureWrite | Boolean | True if this provider can write temperature data. |
Provider Authentication
| JSON Item | Data Type | Description |
|---|---|---|
| providers | Array of ProviderAuthenticationItem | List of providers |
Provider Authentication Item
| JSON Item | Data Type | Description |
|---|---|---|
| name | String | This is the description of the provider for display purposes. |
| providerType | String | This is the value of the providerType to be passed in. This should not be displayed. |
| keys | Array of ProviderAuthenticationKey |
Provider Authentication Key
| JSON Item | Data Type | Description |
|---|---|---|
| name | String | Name of the source or destination task represented here. If there are tasks with duplicate names, there may be an identifier at the end of the name to help with ordering. |
| id | String | Id of the source or destination to be used with the re-use. |
Sync Status Results
| JSON Item | Data Type | Description |
|---|---|---|
| results | Array of SyncStatus |
Sync Status
| JSON Item | Data Type | Description |
|---|---|---|
| id | String | The id of the source or destination. |
| type | String | Indication of the type ranging from SOURCE or DESTINATION. Other types should be ignored. |
| status | String | A summary of the current status, such as Running, Queued, Status, Complete |
| state | String | Which state is this task in; this is not available for all tasks. Generally will be: HISTORIC_SYNC, REFRESHING, COMPARING, SYNCING, UPLOADING |
| info | String | If available, the localized message summarizing the state |
| upTo | Long | Date about how far this has been processed up-to |
| update | String | Any recent error messages from this source or destination. |
Subscription
| JSON Item | Data Type | Description |
|---|---|---|
| notificationKey | String | The notification key for the subscription. This notificationKey will be in each of the notifications executed to your service on behalf of this user. Repeating queries here will result in new keys being created. |
Notification
| JSON Item | Data Type | Description |
|---|---|---|
| claim | String | The claim will be required for deleting the notification. |
| items | Array of Subscription | List of the subscriptions which have data. |
| errors | Array of Subscription | List of the subscriptions which have encountered one or more errors. |
Description Results
| JSON Item | Data Type | Description |
|---|---|---|
| results | Array of Description | The array of results. |
Description
| JSON Item | Data Type | Description |
|---|---|---|
| key | String | This is the key id which is to be referenced within this API. |
| description | String | Description of the item. |
| taskType | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
| isMeasuredType | Boolean | True if this is a measured type where metric or imperial would make a difference. |
| metric | Boolean | True if this value should be used on metric values. False if this is imperial. Null if this is not applicable. |
| onlyReportSettings | Boolean | True if this granularity is only allowed for Report Settings and not for Report Inquiries. |
| measurementType | String | What type of display preference takes precedence when displaying this unit. One of: DISTANCE, WEIGHT, GLUCOSE, TEMPERATURE, NUTRITION, WATER |
Power Zones
| JSON Item | Data Type | Description |
|---|---|---|
| base | Integer | Base Power Zone |
| maxZone1 | Integer | Maximum value for Zone 1 |
| maxZone2 | Integer | Maximum value for Zone 2 |
| maxZone3 | Integer | Maximum value for Zone 3 |
| maxZone4 | Integer | Maximum value for Zone 4 |
| maxZone5 | Integer | Maximum value for Zone 5 |
| maxZone6 | Integer | Maximum value for Zone 6 |
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. |
| 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. |
| 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 |
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. |
Leaderboard Data
| JSON Item | Data Type | Description |
|---|---|---|
| data | LeaderboardData_data |
Leaderboard Data Data
| JSON Item | Data Type | Description |
|---|---|---|
| categories | Array of String | Categories of the chart, in increasing order |
| entries | Array of LeaderboardData_data_entries | Participants |
Leaderboard Data Data Entries
| JSON Item | Data Type | Description |
|---|---|---|
| participant | String | Display name of the participant. |
| values | Array of LeaderboardData_data_values | Values of the Participant |
Leaderboard Data Data Values
| JSON Item | Data Type | Description |
|---|---|---|
| category | String | Category name |
| value | Double | Category value |
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 specifics 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 a null? 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 seperate 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 DashboardResponse_series | Chart Data |
Dashboard Data Series
| JSON Item | Data Type | Description |
|---|---|---|
| label | String | Label of the Row. |
| values | Array of DashboardResponse_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. |
| 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. |
Errors
| JSON Item | Data Type | Description |
|---|---|---|
| error_description | String | Description of the error for end-user consumption. |
Items
Given a TaskType, this is the representation of the data behind it.
Common
| JSON Item | Data Type | Description |
|---|---|---|
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
Activity
This describes an activity. It extends Common where type equals Activity.
| JSON Item | Data Type | Description |
|---|---|---|
| activity | String | General Summary of the Activity or Exercise Type, generally in one word. |
| fitnessSyncerActivity | String | Similar to the activity, however, the activity is the raw string from the service and fitnessSyncerActivity is the FitnessSyncer normalized activity |
| title | String | A human readable title of the activity. |
| distanceKM | Double | Distance of the Activity in KM. Use 0 if not applicable. |
| duration | Double | Duration in Seconds. Use 0 if not applicable. |
| calories | Integer | Calories Burned |
| bmr | Integer | Basal Metabolic Rate |
| endDate | Long | End Time in milliseconds since the Epoch in UTC (if not summary) |
| steps | Integer | Number of steps for this activity. |
| avgHeartrate | Integer | Average heart rate for the activity. |
| minHeartrate | Integer | Minimum heart rate for the activity. |
| maxHeartrate | Integer | Maximum heart rate for the activity. |
| restingHeartrate | Integer | Resting heart rate for the activity. |
| avgStressLevel | Integer | Average Stress Level |
| minStressLevel | Integer | Minimum Stress Level |
| maxStressLevel | Integer | Maximum Stress Level |
| lowStressDurationSeconds | Integer | Seconds Under Low Sttress |
| mediumStressDurationSeconds | Integer | Seconds Under Medium Stress |
| highStressDurationSeconds | Integer | Seconds Under High Stress |
| vo2Max | Integer | VO2Max Level |
| respiratoryRate | Double | Respiratory Rate |
| mindfulMinutes | Integer | Mindful Minutets |
| summary | Boolean | If this is a daily summary snapshot, this will be true. Generally when this is true, the date of the item will also be at midnight UTC of that date. |
| temperatureCelsius | Double | Average Temperature in Celsius |
| repetitions | Integer | Number of repetitions, especially for things like Push-Ups |
| weight | Double | Weights used for the exercise in KG |
| manual | Boolean | True if this was manually entered; false if not know or was not. |
| floorsClimbed | Integer | Approximate Number of Floors Climbed |
| gps | GPSData | |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
GPSData
| JSON Item | Data Type | Description |
|---|---|---|
| id | String | Id of the GPS Event |
| title | String | Title of the Stream |
| sport | String | Sport |
| date | Long | Date of the event as a long of the number of milliseconds since the Epoch in UTC |
| lap | Array of Lap |
Lap
| JSON Item | Data Type | Description |
|---|---|---|
| start | Long | Start time of this Lap in milliseconds since the Epoch in UTC |
| millis | Integer | Duration in milliseconds |
| totalMovingTimeMillis | Integer | Moving Time in milliseconds (if specified) |
| totalMovingTimeMillisCalc | Integer | This will either be equal to totalMovingTimeMillis or be the version we have calculated. This is a read-only field. |
| dist | Integer | Distance in Meters |
| calories | Integer | Calories Expended for this Lap |
| speed | Double | Speed in Meters per Second |
| maxHeart | Double | Maximum heart rate in this Lap |
| avgHeart | Double | Average heart rate in this Lap |
| cadence | Double | Cadence for this Lap |
| sport | String | Only specified if different than the GPSData sport or a multisport activity. |
| notes | Double | Notes for this Lap |
| hrr | Double | Heart Rate Recovery |
| points | Array of Point |
Point
| JSON Item | Data Type | Description |
|---|---|---|
| time | Long | Time of this event in milliseconds since the epoch in UTC |
| distance | Double | Distance in Meters |
| point | LatLng | |
| altitude | Double | Altitude in meters |
| heartRate | Double | Heart rate in beats per minute at this time |
| speed | Double | Speed in meters per second |
| cadence | Double | Cadence |
| calories | Double | Calories Burned |
| hrv | Array of Double | |
| hrv_sdnn | Double | Heart Rate Variability in SDNN |
| power | Double | Power in Watts |
| estimatedPower | Double | Estimated Power in Watts |
| temp | Double | Temperature in Celsius |
| steps | Double | Steps moved up-to this point from the last point. |
| torque | Double | Torque |
| locationAccuracy | Double | Rating of the location accuracy |
| bearing | Double | Bearings in Radians |
| tilt | Double | Tilt in Radians |
| pedometerCadence | Double | Current Cadence |
| crankCadence | Double | Crank Cadence |
| crankRevolutionDelta | Integer | Crank Revolution Delta |
| wheelCadence | Double | Wheel Cadence |
| wheelRevolutionDelta | Integer | Wheel Revolution Delta |
| moving | Boolean | True if this is considered to be in motion. |
| stanceTime | Double | Stance Time |
| legSpringStiffness | Double | Leg Spring Stiffness |
| stress | Double | Stress |
| formPower | Double | Form Power |
| verticalOscilation | Double | Vertical Oscillation |
| vo2Max | Double | VO2 Max |
| respiratoryRate | Double | Respiratory Rate |
LatLng
| JSON Item | Data Type | Description |
|---|---|---|
| lat | Double | Latitude |
| lng | Double | Longitude |
Allergy
This describes an allergy. It extends Common where type equals Allergy.
| JSON Item | Data Type | Description |
|---|---|---|
| allergy | String | Allergy Name |
| isNegated | Boolean | True if the treatment negates the allergy |
| treatment | String | Treatment of allergy |
| endDate | Long | Time in milliseconds since the Epoch in UTC of when this medication was last used. 0 implies that it is ongoing. |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
Weight
This describes a body composition record. It extends Common where type equals Weight.
| JSON Item | Data Type | Description |
|---|---|---|
| weight | Double | Weight in KG |
| height | Double | Height in Meters |
| fatFreeMass | Double | Fat Free Mass in KG |
| fatRatio | Double | Fat Ratio |
| boneMass | Double | Bone Mass in KG |
| bodyWaterKg | Double | Body Water in KG |
| bmi | Double | Body Mass Index. May be calculated if the User Preferences has the user's height. |
| muscleMass | Double | Muscle Mass in KG |
| fatMassWeight | Double | Fat Mass Weight in KG |
| caliperChest | Double | Chest Caliper in MM |
| caliperMidaxillary | Double | Midaxillary Caliper in MM |
| caliperBicep | Double | Bicep Caliper in MM |
| caliperAbdominal | Double | Abdominal Caliper in MM |
| caliperSuprailiac | Double | Suprailiac Caliper in MM |
| caliperThigh | Double | Thigh Caliper in MM |
| caliperCalf | Double | Calf Caliper in MM |
| caliperSubscapular | Double | Subscapular Caliper in MM |
| caliperTricep | Double | Tricep Caliper in MM |
| caliperLowerBack | Double | Lower Back Caliper in MM |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
Blood Pressure
This describes a blood pressure record. It extends Common where type equals BloodPressure.
| JSON Item | Data Type | Description |
|---|---|---|
| diastolic | Double | Diastolic Blood Pressure |
| systolic | Double | Systolic Blood Pressure |
| pulse | Double | Pulse at the time of the reading |
| arrhythmia | Boolean | True if Arrhythmia was detected in this reading. |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
Cholesterol
This describes a cholesterol. It extends Common where type equals Cholesterol.
| JSON Item | Data Type | Description |
|---|---|---|
| ldl | Double | LDL Cholesterol in mmol per Liter |
| hdl | Double | HDL Cholesterol in mmol per Liter |
| totalCholesterol | Double | Total Cholesterol in mmol per Liter |
| triglyceride | Double | Triglyceride in mmol per Liter |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
Condition
This describes a condition. It extends Common where type equals Condition.
| JSON Item | Data Type | Description |
|---|---|---|
| condition | String | Condition Name |
| endDate | Long | Time in milliseconds since the Epoch in UTC of when this medication was last used. 0 implies that it is ongoing. |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
Glucose
This describes a glucose record. It extends Common where type equals Glucose.
| JSON Item | Data Type | Description |
|---|---|---|
| value | Double | Glucose Read in mmol per Liter |
| a1c | Boolean | True if the value was derived from an A1C |
| measurementType | String | Description of the Context, such as whole blood or plasma |
| measurementContext | String | Description of the Context, such as Before Breakfast |
| entries | Array of GlucosePoint | In order to scale, we recommend grouping data per hour. These are the finer grained elements. |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
GlucosePoint
This describes a glucose entry.
| JSON Item | Data Type | Description |
|---|---|---|
| time | Long | Time in milliseconds since the Epoch in UTC |
| value | Double | Glucose Read in mmol per Liter |
Medication
This describes a medication record. It extends Common where type equals Medication.
| JSON Item | Data Type | Description |
|---|---|---|
| medication | String | Medication Name |
| dose | Double | The dose amount of this medication |
| doseUnit | String | The dose unit amount for this type. Must be one of: ML, MG, MCG, MGML, Tablet. |
| strength | Double | The strength amount of this medication |
| strengthUnit | String | The strength unit amount for this type. Must be one of: ML, MCG, MG, MGML |
| endDate | Long | Time in milliseconds since the Epoch in UTC of when this medication was last used. 0 implies that it is ongoing. |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
Nutrition
This describes a nutrition record. It extends Common where type equals Nutrition.
| JSON Item | Data Type | Description |
|---|---|---|
| food | String | Description of the Food Eaten |
| meal | String | Meal that this was eaten at, typically Breakfast, Lunch, Dinner, Snack, or Other |
| mealApproximation | String | Based on the time, this is FitnessSyncer's best approximation of the meal time |
| calories | Double | Number of calories in this meal. This field is required if Water is not present. |
| carbohydrates | Double | Carbohydrates in Grams |
| fat | Double | Fat in Grams |
| fiber | Double | Fiber in Grams |
| protein | Double | Protein in Grams |
| sugar | Double | Sugar in Grams |
| cholesterol | Double | Cholesterol in Grams |
| saturatedFat | Double | Saturated Fat in Grams |
| sodium | Double | Sodium in milligrams |
| iron | Double | Iron in milligrams |
| potassium | Double | Potassium in milligrams |
| vitaminA | Double | Vitamin A in IU |
| vitaminC | Double | Vitamin C in grams |
| vitaminD | Double | Vitamin D in IU |
| calcium | Double | Calcium in grams |
| glycemicLoad | Integer | Glycemic Load |
| water | Double | Number of Fluid Ounces of Water Consumed. This field is required if Calories is not present. |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
Oxygen
This describes an oxygen record. It extends Common where type equals Oxygen.
| JSON Item | Data Type | Description |
|---|---|---|
| spo2 | Double | SpO2 Reading in Percent |
| pulse | Double | Pulse Reading in BPM |
| entries | Array of OxygenPoint | In order to scale, we recommend grouping data per hour. These are the finer grained elements. |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
OxygenPoint
This describes an oxygen entry.
| JSON Item | Data Type | Description |
|---|---|---|
| time | Long | Time in milliseconds since the Epoch in UTC |
| spo2 | Double | SpO2 Reading in Percent |
| pulse | Double | Pulse Reading in BPM |
Sleep
This describes a sleep record. It extends Common where type equals Sleep.
| JSON Item | Data Type | Description |
|---|---|---|
| bedTime | Long | Bed Time in Milliseconds Since Epoch in UTC |
| awakeTime | Long | Awake Time in Milliseconds Since Epoch in UTC |
| sleepingMinutes | Integer | Number of minutes actually asleep |
| awakenings | Integer | Number of times awoken |
| efficiency | Integer | Efficiency of the Sleep as a Percentage |
| sleepEvents | Array of SleepEvent | Actual Sleep Events |
| inferredSleepEvents | Array of SleepEvent | If Actual Sleep Events are not available, FitnessSyncer will provide inferred Sleep Events. This is a read-only parameter. |
| sleepPoints | Array of SleepPoint | |
| settlingMinutes | Integer | Number of Minutes it took to Settle In |
| lightSleepMinutes | Integer | Number of Minutes in Light Sleep |
| l2SleepMinutes | Integer | Number of Minutes in L2 Sleep |
| l3SleepMinutes | Integer | Number of Minutes in L3 Sleep |
| deepSleepMinutes | Integer | Number of Minutes in Deep Sleep |
| remSleepMinutes | Integer | Number of Minutes in REM Sleep |
| awakeMinutes | Integer | Number of Minutes awake. |
| avgHR | Double | Average Heart Rate during Sleep |
| avgRR | Double | Average Respiratory Rate during Sleep |
| hrvRmssdEvening | Double | HRV RMSSD when going to Sleep |
| hrvRmssdMorning | Double | HRV RMSSD when waking up |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
SleepEvent
| JSON Item | Data Type | Description |
|---|---|---|
| type | String | Sleep Stage. Must be one of: LIGHT_SLEEP, ASLEEP, AWAKE, REALLY_AWAKE, REM. |
| offsetMinutes | Double | Minute within the sleep this started. |
| durationMinutes | Double | Number of minutes that this event lasts for. |
SleepPoint
| JSON Item | Data Type | Description |
|---|---|---|
| time | Long | Time in milliseconds since the Epoch in UTC |
| heartRate | Double | Heart rate in beats per minute at this time |
| respiratoryRate | Double | Respiratory Rate |
| hrv_sdnn | Double | Heart Rate Variability in SDNN |
Temperature
This describes a temperature record. It extends Common where type equals Temperature.
| JSON Item | Data Type | Description |
|---|---|---|
| temperature | Double | Temperature Reading in Celsius |
| entries | Array of TemperaturePoint | In order to scale, we recommend grouping data per hour. These are the finer grained elements. |
| providerType | String | An enumeration of the Provider Type for uploading data to this API. |
| date | Long | Time in milliseconds since the Epoch in UTC |
| itemId | String | Id of the item |
| taskId | String | Id of the Source Data |
| comment | String | Comment associated with the data. |
| tags | Array of String | User tag |
| type | String | Enumeration of TaskTypes. Must be one of Activity, Allergy, Weight, BloodPressure, Cholesterol, Condition, Glucose, Medication, Nutrition, Oxygen, Sleep, Temperature |
TemperaturePoint
This describes a temperature entry.
| JSON Item | Data Type | Description |
|---|---|---|
| time | Long | Time in milliseconds since the Epoch in UTC |
| value | Double | Temperature Reading in Celsius |
Daily Summary Data
Activities serve both as an event and a daily aggregation of data. The difference is the summary flag. For items where the summary flag is enabled, the date associated with that item should be midnight UTC. The data should be the daily summary. Only one summary per day is allowed. When uploading, you must send the entire data not just the delta.
Character Sets
All requests to FitnessSyncer should be in the UTF-8 character set.
Language
FitnessSyncer accepts and supports the Accept-Language header and will produce the appropriate content for the user.
Compression
To save on bandwidth, you may request GZIP content. For downloads, include the Accept-Encoding: gzip header and include Content-Encoding: gzip header for uploads.
Edge Cases
You should URL encode the itemId that is sent as part of a URL in the cases that there are spaces, slashes, or other characters in it.
Rate Limits
FitnessSyncer may enforce rate limits based on your use-case. When a rate limit is exceeded, an HTTP Error Code of 429 will be returned; this response may include a Retry-After but is not guaranteed to, and if it is missing, you should retry after some time.
If you encounter regular rate limits, please contact us and we can assist in you adjusting your code to not encounter the issue or raise the limit.
Errors
The Error type is returned with each error, which includes an error_description. Here is a sample error:
If you encounter regular problems with a request, you should send us the date and x-fs-srvr-id headers so that we can investigate.
All 500 errors should be retried with exponential backoff.
FitnessSyncer changes DNS configuration to control certain aspects of our availability. Please ensure that your system does not cache DNS entries beyond our DNS TTL configuration. Failure to do so may result in request failures which are not covered by out SLA.
Future Proofing
This API will change over time. In general, the API will be augmented with new functionality and parameters. You should ignore any data for which your application does not presently understand.
In the event that the API must be changed in a non-backwards compatible way, you will be notified via the e-mail address registered with us.
It should also be noted that validation might change over time, which may introduce new errors in your application. Regular testing is encouraged.
Developer Support
Developer support can be done via our normal support process of contacting us.
