Fitbit API

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.

Note
These API methods are only compatible with V1 of the Device Data API. See Device Data API Versions for details.

Contents

Prerequisites
Units
Get Data Summaries
Query Daily Summaries
Query Sleep Logs

Prerequisites

For data to be available, your project must first enable Fitbit data collection and the participant must choose to share their Fitbit data with MyDataHelps.

Units

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 Data Summaries

GET api/v1/administration/projects/:projectID/fitbit

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.

Query Parameters

participantID guid

Search for a participant based on the participant’s internal, stable, unique ID field.

participantIdentifier string

Search for a participant based on the project-set, unique participant identifier.

startDate date

Search for data after this starting date, in ISO8601 format.

endDate date

Search for data before this ending date, in ISO8601 format.

Response Fields

dailySummaries object

Reports how many daily summaries are available.

Child Fields

dailySummaries.count int

Number of data samples available.

dailySummaries.mostRecentResultDate date

Date of the most recent data sample, in ISO8601 format.

sleepLogs object

Reports how many sleep logs are available.

Child Fields

sleepLogs.count int

Number of data samples available.

sleepLogs.mostRecentResultDate date

Date of the most recent data sample, in ISO8601 format.

Sort Order

Results are returned in descending order by date.

    Sample Response 
    
  

    {
    "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"
    }
}

Query Daily Summaries

GET api/v1/administration/projects/:projectID/fitbit/dailySummaries

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:

Query Parameters

participantID guid

Search for a participant based on the participant’s internal, stable, unique ID field.

participantIdentifier string

Search for a participant based on the project-set, unique participant identifier.

startDate date

Search for data after this starting date, in ISO8601 format.

endDate date

Search for data before this ending date, in ISO8601 format.

pageSize int

How many entries to include in each page of results. Default and maximum is 25.

pageID guid

Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that as pageID to query the next page. When excluded, retrieves the first page.

Response Fields

results collection

Daily summaries.

Element Fields

results[n].date date

Date the summary is for, in ISO8601 format.

results[n].activityCalories int

Calories burned from periods above sedentary level.

results[n].bodyBMI double

Body mass index.

results[n].bodyFat double

Body fat.

results[n].bodyWeight double

Body weight.

results[n].calories int

Calories.

results[n].caloriesBMR int

Only BMR (Basal Metabolic Rate) calories.

results[n].distance double

Distance traveled.

results[n].elevation double

Elevation traveled.

results[n].foodCaloriesIn int

Food calories in.

results[n].floors double

Floors climbed.

results[n].heartRateZones object

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.

results[n].minutesFairlyActive int

Minutes spent fairly active.

results[n].minutesLightlyActive int

Minutes spent lightly active.

results[n].minutesSedentary int

Minutes spent sedentary.

results[n].minutesVeryActive int

Minutes spent very active.

results[n].steps int

Steps taken.

results[n].tracker object

Some of the same data as the other fields, but from tracker sources only, not manually-entered data.

results[n].water double

Water intake.

results[n].restingHeartRate int

Average resting heart rate.

results[n].modifiedDate date

Date the summary was last modified, in ISO8601 format.

nextPageID guid

Identifier that you can use to retrieve the next page of results.

Sort Order

Results are returned in descending order by date.

    Sample Response 
    
  

    {
    "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,
            ...
        }
    ]
}

Query Sleep Logs

GET api/v1/administration/projects/:projectID/fitbit/sleepLogs

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.

Query Parameters

participantID guid

Search for a participant based on the participant’s internal, stable, unique ID field.

participantIdentifier string

Search for a participant based on the project-set, unique participant identifier.

startDate date

Search for data after this starting date, in ISO8601 format.

endDate date

Search for data before this ending date, in ISO8601 format.

pageSize int

How many entries to include in each page of results. Default and maximum is 25.

pageID guid

Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that as pageID to query the next page. When excluded, retrieves the first page.

Response Fields

results collection

Sleep logs.

Element Fields

results[n].startTimestamp date

Starting date/time of the log entry, in ISO8601 format.

results[n].endTimestamp date

Ending date/time of the log entry, in ISO8601 format.

results[n].duration int

Sleep duration, in milliseconds.

results[n].efficiency int

A gauge of sleep efficiency.

results[n].timeInBed int

Minutes the user spent in bed.

results[n].infoCode string

Numeric code corresponding to the Type value.

results[n].type string

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).

results[n].minutesAfterWakeup int

Minutes it took the user to get out of bed after waking.

results[n].minutesAsleep int

Minutes the user spent asleep.

results[n].minutesAwake int

Minutes the user spent awake.

results[n].minutesToFallAsleep int

Minutes it took the user to fall asleep.

results[n].isMainSleep boolean

Whether this is the user’s main sleep period (i.e., not a nap).

results[n].logType string

Whether the sleep data was manually logged or edited (manual) or automatically detected (auto_detected).

results[n].sleepLevelAwake int

Minutes spent awake, when the data type is classic.

results[n].sleepLevelAsleep int

Minutes spent asleep, when the data type is classic.

results[n].sleepLevelRestless int

Minutes spent in restless sleep, when the data type is classic.

results[n].sleepLevelDeep int

Minutes spent in deep sleep, when the data type is stages.

results[n].sleepLevelLight int

Minutes spent in light sleep, when the data type is stages.

results[n].sleepLevelRem int

Minutes spent in rem sleep, when the data type is stages.

results[n].sleepLevelWake int

Minutes spent awake, when the data type is stages.

nextPageID guid

Identifier that you can use to retrieve the next page of results.

Sort Order

Results are returned in descending order by date.

    Sample Response 
    
  

    {
    "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,
            ...
        }
    ]
}