With the Fitbit API, you can access Fitbit data from your participants. Raw data is also available in the Device Data API, but the Fitbit API encapsulates commonly-referenced data into an easy-to-use form.
Fitbit uses standard metric units for most measurements.
Unit Type | Units |
---|---|
Duration | milliseconds |
Distance | kilometers |
Elevation | meters |
Height | centimeters |
Weight | kilograms |
Body measurements | centimeters |
Liquids | milliliters |
Blood Glucose | millimoles per liter (mmol/l) (molar concentration) |
GET api/v1/administration/projects/:projectID/fitbit?participantIdentifier=PT-123&startDate=2021-12-01T12:00:00.196-05:00
The data summary query can give a quick overview of how many Fitbit data entries a given participant has, and how recent the results are.
Search for a participant based on the participant’s internal ‘id’ field.
Search for a participant based on the project-specific participant identifier.
Search for data after this starting date, in ISO8601 format.
Search for data before this ending date, in ISO8601 format.
Reports how many daily summaries are available.
Number of data samples available.
Date of the most recent data sample, in ISO8601 format.
Reports how many sleep logs are available.
Number of data samples available.
Date of the most recent data sample, in ISO8601 format.
{
"dailySummaries": {
"count": 477,
"mostRecentResultDate": "2021-12-09T00:00:00"
},
"sleepLogs": {
"count": 453,
"mostRecentResultDate": "2021-12-08T06:30:00"
}
}
{
"dailySummaries": {
"count": 477,
"mostRecentResultDate": "2021-12-09T00:00:00"
},
"sleepLogs": {
"count": 453,
"mostRecentResultDate": "2021-12-08T06:30:00"
}
}
GET api/v1/administration/projects/:projectID/fitbit/dailySummaries?participantIdentifier=PT-123
The Fitbit daily summary contains a daily summary of a variety of Fitbit data, both manually-entered and retrieved from trackers. See the Fitbit documentation for more information about using and interpreting Fitbit data. The daily summaries contain information from various Fitbit APIs:
Search for a participant based on the participant’s internal ‘id’ field.
Search for a participant based on the project-specific participant identifier.
Search for data after this starting date, in ISO8601 format.
Search for data before this ending date, in ISO8601 format.
How many entries to include in each page of results. Default and maximum is 25.
Each page of results will return a nextPageID
if there are additional pages that can be queried. Supply that to pageID
to query the next page. When excluded, retrieves the first page.
Daily summaries.
Date the summary is for, in ISO8601 format.
Calories burned from periods above sedentary level.
Body mass index.
Body fat.
Body weight.
Calories.
Only BMR (Basal Metabolic Rate) calories.
Distance traveled.
Elevation traveled.
Food calories in.
Floors climbed.
Heart rate zones. Each zone provides a minimum and maximum heart rate that together define the zone, number of minutes spent in that zone, and number of calories burned while in that zone.
Minutes spent fairly active.
Minutes spent lightly active.
Minutes spent sedentary.
Minutes spent very active.
Steps taken.
Some of the same data as the other fields, but from tracker sources only, not manually-entered data.
Water intake.
Average resting heart rate.
Date the summary was last modified, in ISO8601 format.
Identifier that you can use to retrieve the next page of results.
{
"nextPageID": "107091f7-e145-ec11-aaa5-fa441d4195e8",
"results": [
{
"date": "2021-12-02T00:00:00",
"activityCalories": 993,
"bodyBMI": 19.682584762573242,
"bodyFat": 0.0,
"bodyWeight": 65.771,
"calories": 2338,
"caloriesBMR": 1583,
"distance": 6.4997099999999994,
"elevation": 112.0,
"foodCaloriesIn": 0,
"floors": 37.0,
"heartRateZones": {
"fatBurn": {
"caloriesOut": 0.0,
"min": 106,
"max": 131,
"minutes": 0
},
...
"cardio": {
"caloriesOut": 0.0,
"min": 131,
"max": 162,
"minutes": 0
}
},
"minutesFairlyActive": 16,
"minutesLightlyActive": 234,
"minutesSedentary": 649,
"minutesVeryActive": 14,
"steps": 8573,
"tracker": {
"activityCalories": 993,
"calories": 2338,
...
"steps": 8573
},
"water": 0.0,
"modifiedDate": "2021-12-09T07:02:19.91Z",
"restingHeartRate": 57
},
{
"date": "2021-12-01T00:00:00",
"activityCalories": 1216,
"bodyBMI": 19.682584762573242,
"bodyFat": 0.0,
"bodyWeight": 65.771,
...
}
]
}
{
"nextPageID": "107091f7-e145-ec11-aaa5-fa441d4195e8",
"results": [
{
"date": "2021-12-02T00:00:00",
"activityCalories": 993,
"bodyBMI": 19.682584762573242,
"bodyFat": 0.0,
"bodyWeight": 65.771,
"calories": 2338,
"caloriesBMR": 1583,
"distance": 6.4997099999999994,
"elevation": 112.0,
"foodCaloriesIn": 0,
"floors": 37.0,
"heartRateZones": {
"fatBurn": {
"caloriesOut": 0.0,
"min": 106,
"max": 131,
"minutes": 0
},
...
"cardio": {
"caloriesOut": 0.0,
"min": 131,
"max": 162,
"minutes": 0
}
},
"minutesFairlyActive": 16,
"minutesLightlyActive": 234,
"minutesSedentary": 649,
"minutesVeryActive": 14,
"steps": 8573,
"tracker": {
"activityCalories": 993,
"calories": 2338,
...
"steps": 8573
},
"water": 0.0,
"modifiedDate": "2021-12-09T07:02:19.91Z",
"restingHeartRate": 57
},
{
"date": "2021-12-01T00:00:00",
"activityCalories": 1216,
"bodyBMI": 19.682584762573242,
"bodyFat": 0.0,
"bodyWeight": 65.771,
...
}
]
}
GET api/v1/administration/projects/:projectID/fitbit/sleepLogs?participantIdentifier=PT-123
The sleep log contains a high-level summary of a participant’s daily sleep patterns. See the Fitbit documentation for more information about using and interpreting Fitbit data.
Search for a participant based on the participant’s internal ‘id’ field.
Search for a participant based on the project-specific participant identifier.
Search for data after this starting date, in ISO8601 format.
Search for data before this ending date, in ISO8601 format.
How many entries to include in each page of results. Default and maximum is 25.
Each page of results will return a nextPageID
if there are additional pages that can be queried. Supply that to pageID
to query the next page. When excluded, retrieves the first page.
Sleep logs.
Starting date/time of the log entry, in ISO8601 format.
Ending date/time of the log entry, in ISO8601 format.
Sleep duration, in milliseconds.
A gauge of sleep efficiency.
Minutes the user spent in bed.
Numeric code corresponding to the Type value.
Fitbit provides two kinds of sleep data: stages (reports data with 30-second granularity, and grades sleep as deep, light, rem, or wake) and classic (reports data with 60-second granularity, and grades sleep as asleep, restless, or awake).
Minutes it took the user to get out of bed after waking.
Minutes the user spent asleep.
Minutes the user spent awake.
Minutes it took the user to fall asleep.
Whether this is the user’s main sleep period (i.e., not a nap).
Whether the sleep data was manually logged or edited (manual
) or automatically detected (auto_detected
).
Minutes spent awake, when the data type is classic.
Minutes spent asleep, when the data type is classic.
Minutes spent in restless sleep, when the data type is classic.
Minutes spent in deep sleep, when the data type is stages.
Minutes spent in light sleep, when the data type is stages.
Minutes spent in rem sleep, when the data type is stages.
Minutes spent awake, when the data type is stages.
Identifier that you can use to retrieve the next page of results.
{
"nextPageID": "c1fa9bf2-bd58-ec11-aaa7-bdf48d06ec26",
"results": [
{
"startTimestamp": "2021-12-07T22:56:00",
"endTimestamp": "2021-12-08T06:30:00",
"duration": 27240000,
"efficiency": 68,
"timeInBed": 454,
"infoCode": "0",
"type": "stages",
"minutesAfterWakeup": 11,
"minutesAsleep": 397,
"minutesAwake": 57,
"minutesToFallAsleep": 6,
"isMainSleep": true,
"logType": "auto_detected",
"sleepLevelAwake": null,
"sleepLevelAsleep": null,
"sleepLevelRestless": null,
"sleepLevelDeep": 73,
"sleepLevelLight": 258,
"sleepLevelRem": 66,
"sleepLevelWake": 57
},
{
"startTimestamp": "2021-12-06T22:55:00",
"endTimestamp": "2021-12-07T06:27:00",
"duration": 27120000,
"efficiency": 61,
"timeInBed": 452,
...
}
]
}
{
"nextPageID": "c1fa9bf2-bd58-ec11-aaa7-bdf48d06ec26",
"results": [
{
"startTimestamp": "2021-12-07T22:56:00",
"endTimestamp": "2021-12-08T06:30:00",
"duration": 27240000,
"efficiency": 68,
"timeInBed": 454,
"infoCode": "0",
"type": "stages",
"minutesAfterWakeup": 11,
"minutesAsleep": 397,
"minutesAwake": 57,
"minutesToFallAsleep": 6,
"isMainSleep": true,
"logType": "auto_detected",
"sleepLevelAwake": null,
"sleepLevelAsleep": null,
"sleepLevelRestless": null,
"sleepLevelDeep": 73,
"sleepLevelLight": 258,
"sleepLevelRem": 66,
"sleepLevelWake": 57
},
{
"startTimestamp": "2021-12-06T22:55:00",
"endTimestamp": "2021-12-07T06:27:00",
"duration": 27120000,
"efficiency": 61,
"timeInBed": 452,
...
}
]
}