Fitbit Data

Although complete Fitbit data can be queried via the Device Data methods, several specific methods exist to aggregate commonly-used data in useful ways.

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

Contents

Prerequisites
Units
Query Fitbit Daily Summaries
Query Fitbit 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)

Query Fitbit Daily Summaries

MyDataHelps.queryFitbitDailySummaries(queryParameters)

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:

Parameters

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.

Returns

Promise<FitbitDailySummariesResult>

Resolves to a result object containing a page of activity summaries.

Element Fields

result.results collection

Daily summaries.

Element Fields

result.results[n].date date

Date the summary is for, in ISO8601 format.

result.results[n].activityCalories int

Calories burned from periods above sedentary level.

result.results[n].bodyBMI double

Body mass index.

result.results[n].bodyFat double

Body fat.

result.results[n].bodyWeight double

Body weight.

result.results[n].calories int

Calories.

result.results[n].caloriesBMR int

Only BMR (Basal Metabolic Rate) calories.

result.results[n].distance double

Distance traveled.

result.results[n].elevation double

Elevation traveled.

result.results[n].foodCaloriesIn int

Food calories in.

result.results[n].floors double

Floors climbed.

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

result.results[n].minutesFairlyActive int

Minutes spent fairly active.

result.results[n].minutesLightlyActive int

Minutes spent lightly active.

result.results[n].minutesSedentary int

Minutes spent sedentary.

result.results[n].minutesVeryActive int

Minutes spent very active.

result.results[n].steps int

Steps taken.

result.results[n].tracker object

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

result.results[n].water double

Water intake.

result.results[n].restingHeartRate int

Average resting heart rate.

result.results[n].modifiedDate date

Date the summary was last modified, in ISO8601 format.

result.nextPageID guid

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

Availability

MyDataHelps Views

MyDataHelps Embeddables

Web View Steps

    Querying Fitbit Daily Summaries 
    
  

    var queryParameters = {
	startDate: "2021-02-18",
	endDate: "2021-03-01T12:00:00-4:00",
	pageSize: 25,
	pageID: "c123b398-bf20-4b6f-989c-b0dcb4c3d75c"
};

MyDataHelps.queryFitbitDailySummaries(queryParameters)
	.then( function(result) {
		console.log(result);
	} );
  var queryParameters = {
	startDate: "2021-02-18",
	endDate: "2021-03-01T12:00:00-4:00",
	pageSize: 25,
	pageID: "c123b398-bf20-4b6f-989c-b0dcb4c3d75c"
};

MyDataHelps.queryFitbitDailySummaries(queryParameters)
	.then( function(result) {
		console.log(result);
	} );

    Sample Response Data 
    
  

    {
    "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 Fitbit Sleep Logs

MyDataHelps.queryFitbitSleepLogs(queryParameters)

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.

Parameters

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.

Returns

Promise<FitbitSleepLogsResult>

Resolves to a result object containing a page of sleep logs.

Element Fields

result.results collection

Sleep logs.

Element Fields

result.results[n].startTimestamp date

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

result.results[n].endTimestamp date

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

result.results[n].duration int

Sleep duration, in milliseconds.

result.results[n].efficiency int

A gauge of sleep efficiency.

result.results[n].timeInBed int

Minutes the user spent in bed.

result.results[n].infoCode string

Numeric code corresponding to the Type value.

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

result.results[n].minutesAfterWakeup int

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

result.results[n].minutesAsleep int

Minutes the user spent asleep.

result.results[n].minutesAwake int

Minutes the user spent awake.

result.results[n].minutesToFallAsleep int

Minutes it took the user to fall asleep.

result.results[n].isMainSleep boolean

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

result.results[n].logType string

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

result.results[n].sleepLevelAwake int

Minutes spent awake, when the data type is classic.

result.results[n].sleepLevelAsleep int

Minutes spent asleep, when the data type is classic.

result.results[n].sleepLevelRestless int

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

result.results[n].sleepLevelDeep int

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

result.results[n].sleepLevelLight int

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

result.results[n].sleepLevelRem int

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

result.results[n].sleepLevelWake int

Minutes spent awake, when the data type is stages.

result.nextPageID guid

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

Availability

MyDataHelps Views

MyDataHelps Embeddables

Web View Steps

    Querying Fitbit Sleep Logs 
    
  

    var queryParameters = {
	startDate: "2021-02-18",
	endDate: "2021-03-01T12:00:00-4:00",
	pageSize: 25,
	pageID: "c123b398-bf20-4b6f-989c-b0dcb4c3d75c"
};

MyDataHelps.queryFitbitSleepLogs(queryParameters)
	.then( function(result) {
		console.log(result);
	} );
  var queryParameters = {
	startDate: "2021-02-18",
	endDate: "2021-03-01T12:00:00-4:00",
	pageSize: 25,
	pageID: "c123b398-bf20-4b6f-989c-b0dcb4c3d75c"
};

MyDataHelps.queryFitbitSleepLogs(queryParameters)
	.then( function(result) {
		console.log(result);
	} );

    Sample Response Data 
    
  

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