Activity & Exercise Logs

Get Daily Activity Summary

The Get Daily Activity Summary endpoint retrieves a summary and list of a user's activities and activity log entries for a given day in the format requested using units in the unit system which corresponds to the Accept-Language header provided.

Privacy Setting

The Activities (Friends or Anyone) privacy permission grants access to a user's resource with the exception that the response DOES NOT include a detailed list of activity log entries.

Considerations

  1. Daily summary data and daily goals for elevation (elevation, floors) only included for users with a device with an altimeter.

  2. The steps field in activity log entires included only for activities that have steps (e.g. "Walking", "Running"); distance only included when it is relevant.

  3. A false value for field means that activity log entry was created without explicit start time via some of our data import workflows. The field for such entry is commonly set to 00:00.

  4. Calorie burn goal (caloriesOut) represents either dynamic daily target from the premium trainer plan or manual calorie burn goal. Goals are included to the response only for today and 21 days in the past.

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/activities/date/[date].json
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.
date The date in the format yyyy-MM-dd

Request Headers

Accept-Locale optional The locale to use for response values.
Accept-Language optional The measurement unit system to use for response values.

Example Response

{
    "activities":[
        {
            "activityId":51007,
            "activityParentId":90019,
            "calories":230,
            "description":"7mph",
            "distance":2.04,
            "duration":1097053,
            "hasStartTime":true,
            "isFavorite":true,
            "logId":1154701,
            "name":"Treadmill, 0% Incline",
            "startTime":"00:25",
            "steps":3783
        }
    ],
    "goals":{
        "caloriesOut":2826,
        "distance":8.05,
        "floors":150,
        "steps":10000
     },
    "summary":{
        "activityCalories":230,
        "caloriesBMR":1913,
        "caloriesOut":2143,
        "distances":[
            {"activity":"tracker", "distance":1.32},
            {"activity":"loggedActivities", "distance":0},
            {"activity":"total","distance":1.32},
            {"activity":"veryActive", "distance":0.51},
            {"activity":"moderatelyActive", "distance":0.51},
            {"activity":"lightlyActive", "distance":0.51},
            {"activity":"sedentaryActive", "distance":0.51},
            {"activity":"Treadmill, 0% Incline", "distance":3.28}
        ],
        "elevation":48.77,
        "fairlyActiveMinutes":0,
        "floors":16,
        "lightlyActiveMinutes":0,
        "marginalCalories":200,
        "sedentaryMinutes":1166,
        "steps":0,
        "veryActiveMinutes":0
    }
}

Activity Time Series

Get Activity Time Series

The Get Activity Time Series endpoint returns time series data in the specified range for a given resource in the format requested using units in the unit system that corresponds to the Accept-Language header provided.

Considerations

  1. Even if you provide earlier dates in the request, the response will retrieve only data since the user's join date or the first log entry date for the requested collection.

  2. The activities/tracker/... resource represents the daily activity values logged by the tracker device only, excluding manual activity log entries.

  3. The activities/tracker/calories resource does not include the Estimated Energy Requirement for calorie estimation (EER) calculations for any dates even if they are turned on for the user's profile and use BMR level instead.

  4. The activities collection is maintained as a backwards compatible resource urls (e.g. activities/log/calories).

  5. Elevation time series (/elevation, /floors) are only available for users with compatible trackers.

Resource URL

There are two acceptable formats for retrieving activity time series data:

GET /1/user/[user-id]/[resource-path]/date/[date]/[period].json
GET /1/user/[user-id]/[resource-path]/date/[base-date]/[end-date].json
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.
resource-path The resource path; see options in the "Resource Path Options" section below.
base-date The range start date, in the format yyyy-MM-dd or today.
end-date The end date of the range.
date The end date of the period specified in the format yyyy-MM-dd or today.
period The range for which data will be returned. Options are 1d, 7d, 30d, 1w, 1m, 3m, 6m, 1y

Resource Path Options

ACTIVITY

activities/calories
activities/caloriesBMR
activities/steps
activities/distance
activities/floors
activities/elevation
activities/minutesSedentary
activities/minutesLightlyActive
activities/minutesFairlyActive
activities/minutesVeryActive
activities/activityCalories

TRACKER ACTIVITY

activities/tracker/calories
activities/tracker/steps
activities/tracker/distance
activities/tracker/floors
activities/tracker/elevation
activities/tracker/minutesSedentary
activities/tracker/minutesLightlyActive
activities/tracker/minutesFairlyActive
activities/tracker/minutesVeryActive
activities/tracker/activityCalories

Request Headers

Accept-Language optional The language to use for response values. Language is used to determine the activity measurement units returned.

Example Request

GET https://api.fitbit.com/1/user/-/activities/steps/date/today/1m.json

Calorie Time Series Differences

  • activities/calories - The top level time series for calories burned inclusive of BMR, tracked activity, and manually logged activities.

  • activities/caloriesBMR - Only BMR calories.

  • activities/activityCalories - The number of calories burned during the day for periods of time when the user was active above sedentary level. This value is calculated minute by minute for minutes that fall under this criteria. This includes BMR for those minutes as well as activity burned calories.

  • activities/tracker/calories - Calories burned inclusive of BMR according to movement captured by a Fitbit tracker.

  • activities/tracker/activityCalories - Calculated similarly to activities/activityCalories, but uses only tracker data. This means that manually logged activities are excluded.

Example Response

{
    "activities-log-steps":[
        {"dateTime":"2011-04-27","value":5490},
        {"dateTime":"2011-04-28","value":2344},
        {"dateTime":"2011-04-29","value":2779},
        {"dateTime":"2011-04-30","value":9196},
        {"dateTime":"2011-05-01","value":15828},
        {"dateTime":"2011-05-02","value":1945},
        {"dateTime":"2011-05-03","value":366}
    ]
}

Get Activity Intraday Time Series

Access to the Intraday Time Series for personal use (accessing your own data) is available through the "Personal" App Type.

Access to the Intraday Time Series for all other uses is currently granted on a case-by-case basis. Applications must demonstrate necessity to create a great user experience. Fitbit is very supportive of non-profit research and personal projects. Commercial applications require thorough review and are subject to additional requirements. Only select applications are granted access and Fitbit reserves the right to limit this access. To request access, fill out the form here

This endpoint returns the Intraday Time Series for a given resource in the format requested. The endpoint mimics the Get Activity Time Series endpoint. If your application has the appropriate access, your calls to a time series endpoint for a specific day (by using start and end dates on the same day or a period of 1d), the response will include extended intraday values with a 1-minute detail level for that day. Unlike other time series calls that allow fetching data of other users, intraday data is available only for and to the authorized user.

Considerations

  1. If your application's http client is sensitive to the content-length of the response, you will likely prefer JSON as a response format to minimize the amount of data in the response.

  2. If a user hasn't synced a tracker for more than seven (7) days, the tracker stores only summary values for the days older than one week. In this case, the intraday data for steps is zero and the intraday calories are calculated from BMR or EER. Intraday steps could be estimated from the total daily summary data by the equation above.

  3. For the current day we will include only values until current timestamp (in the user's timezone).

  4. If a specific time interval was passed to the call via start-time/end-time parameters, data-value will include a summary only for the requested time period (versus whole day).

  5. For the activities/log/calories resource, each data point also includes the level field that reflects calculated activity level for that time period ( 0 - sedentary; 1 - lightly active; 2 - fairly active; 3 - very active.)

  6. If BMR or EER have been used to estimate calories for the whole specific day (no tracker data), intraday data for calories would be flat and estimated according to the simple equation calories_1m = BMR(EER)/24/60.

Using BMR/EER Algorithms

If a user had no Fitbit tracker data for the specific day then the greater of Logged Activities + BMR (for minutes when there is no activity) and the calories calculated from the EER for that day (if EER enabled for this user's profile) are taken. In case, there was some data from the tracker for the specific day, that data where available is used and for time where data is unavailable, the BMR is used. If the total is less than 20% greater than BMR then the EER (cals < EER * 0.8) is used. EER never used to calculate calories for today.

Using BMR Formula

Fitbit uses the standard MD Mifflin-St Jeor equation:

9.99 * weightKg + 6.25*heightCm - 4.92*ageYears + s, where s is +5 for males
and -161 for female

EER Formula (TEE total energy expenditure)

The EER Formula is based on http://www.cdc.gov/pcd/issues/2006/oct/pdf/06_0034.pdf, which in turn is based on "Food and Nutrition Board. Dietary reference intakes for energy, carbohydrate, fiber, fat, fatty acids, cholesterol, protein, and amino acids (macronutrients). Washington (DC): National Academy Press; 2005." http://www.nap.edu/openbook.php?isbn=0309085373&page=204

MALE-based EER Formula:

TEE = 864 - 9.72 x age (years) + 1.0 x (14.2 x weight(kg) + 503 x height
(meters))

FEMALE-based EER Formula:

TEE = 387 - 7.31 x age (years) + 1.0 x (10.9 x weight(kg) + 660.7 x height
(meters))

Resource URLs

There are four acceptable formats for retrieving activity intraday time series data:

GET https://api.fitbit.com/1/user/-/[resource-path]/date/[date]/[date]/[detail-level].json
GET https://api.fitbit.com/1/user/-/[resource-path]/date/[date]/1d/[detail-level].json
GET https://api.fitbit.com/1/user/-/[resource-path]/date/[date]/[date]/[detail-level]/time/[start-time]/[end-time].json
GET https://api.fitbit.com/1/user/-/[resource-path]/date/[date]/1d/[detail-level]/time/[start-time]/[end-time].json
resource-path The resource path of the desired data.
date The date, in the format yyyy-MM-dd or today.
detail-level Number of data points to include. Either 1min or 15min. Optional.
start-time The start of the period, in the format HH:mm. Optional.
end-time The end of the period, in the format HH:mm. Optional.

Resource Path Options

activities/calories
activities/steps
activities/distance
activities/floors
activities/elevation

Request Headers

Accept-Language optional The language to use for response values. Language is used to determine the activity measurement units returned.

Example Requests

Here are three examples of request:

GET /1/user/-/activities/calories/date/2014-09-01/2014-09-01.json
GET /1/user/-/activities/steps/date/2014-09-01/1d.json
GET /1/user/-/activities/calories/date/2014-09-01/1d/15min/time/12:30/12:45.json

Example Response

{
    "activities-steps":[
        {"dateTime":"2014-09-05","value":1433}
    ],
    "activities-steps-intraday":{
        "dataset":[
            {"time":"00:00:00","value":0},
            {"time":"00:01:00","value":0},
            {"time":"00:02:00","value":0},
            {"time":"00:03:00","value":0},
            {"time":"00:04:00","value":0},
            {"time":"00:05:00","value":287},
            {"time":"00:06:00","value":287},
            {"time":"00:07:00","value":287},
            {"time":"00:08:00","value":287},
            {"time":"00:09:00","value":287},
            {"time":"00:10:00","value":0},
            {"time":"00:11:00","value":0},
        ],
        "datasetInterval":1,
        "datasetType": "minute"
    }
}

Activity Logging

Log Activity

The Log Activity endpoint creates log entry for an activity or user's private custom activity using units in the unit system which corresponds to the Accept-Language header provided (or using optional custom distanceUnit) and get a response in the format requested.

Activity Types

Any activity log entry is based on the one of activities from the catalog of activities. Though activities in catalog have a tree structure (i.e. divided into categories like "Sports and Workouts", "Running" and subcategories like "Bicycling", "Walking"), each activity leaf in the catalog can also have more granular structure. Each leaf can have a directory activity type (and have child intensity levels) or simple activity (have no levels). So, when creating a new activity log entry, use the following types of objects to passed as the activityId value:

  • Directory activity id: activity contains child activities which represents intensity levels (e.g. "Running").

  • Intensity level id: activity within directory activity (e.g. "Running/6.7mph (9 min/mile)").

  • Simple activity id: single activity without intensity levels (e.g. "Shoveling snow").

    Note: A list of activities can be retrieved via the Browse Activities endpoint.

Custom Activities

In the process of creating new activity log entry it is possible to seamlessly create new custom activity for the user. It could be achieved using the second scenario for the set of POST parameters (providing activityName instead of activityId). In this case, either existing custom activity with the same name will be used for creating new log entry or a new record created and then logged. As for custom activities on the website, manualCalories must always provided with the activityName parameter among other required fields.

Resource URLs

POST https://api.fitbit.com/1/user/-/activities.json

Request Headers

Accept-Locale optional The locale to use for response values.
Accept-Language optional The measurement unit system to use for POST parameters and response values.

POST Parameters

activityId optional/required This is the Activity ID of the activity, directory activity, or intensity level activity. If you pass directory activity id, Fitbit calculates and substitutes it with the corresponding intensity level activity id based on the specified distance and/or duration.
activityName optional/required Custom activity name. Either activityId or activityName must be provided.
manualCalories optional/required Calories burned, specified manually. Required with activityName parameter, otherwise optional.
startTime required Activity start time. Hours and minutes in the format HH:mm:ss.
durationMillis required Duration in milliseconds.
date required Log entry date; in the format yyyy-MM-dd.
distance optional/required Distance; required for logging directory activity. In the format X.XX and in the selected distanceUnit or in the unit system that corresponds to the Accept-Language header provided.
distanceUnit optional Distance measurement unit. Steps units are available only for "Walking" (activityId=90013) and "Running" (activityId=90009) directory activities and their intensity levels.

Response Body Format

Note: Text within the <> brackets is a descriptive placeholder for a value or repeated elements.

{
    "activityLog":{
        "activityId":<value>,
        "activityParentId":<value>,
        "calories":<value>,
        "description":<value>,
        "distance":<value>,
        "duration":<value>,
        "isFavorite":<value>,
        "logId":<value>,
        "name":<value>,
        "startTime":<value>,
        "steps":<value>
    }
}
{
    "activityLog":{
        "activityId":12030,
        "activityParentId":90009,
        "calories":197,
        "description":"5 mph (12 min/mile)",
        "distance":3.34,
        "duration":1800000,
        "isFavorite":false,
        "logId":132394,
        "name":"Running",
        "startTime":"12:20",
        "steps":2970
    }
}

Note: The steps field is only included for activities that have steps ("Walking" or "Running") and distance is only included when it is relevant.

Delete Activity Log

The Delete Activity Log endpoint deletes a user's activity log entry with the given ID. A successful request will return a 204 status code with an empty response body.

Resource URLs

DELETE /1/user/-/activities/[activity-log-id].json
activity-log-id The id of the activity log entry.

Get Activity Logs List

The Get Activity Logs List endpoint retrieves a list of a user's activity log entries before or after a given day with offset and limit using units in the unit system which corresponds to the Accept-Language header provided.

The type of activity log can be determined by the logType property.

  • auto_detected activity logs are those created by Fitbit’s SmartTrack feature.

  • fitstar activity logs are created after completing a FitStar workout.

  • manual activity logs are user specified overrides of some or all tracker data.

  • mobile_run activity logs are created after completing a MobileRun.

  • tracker activity logs are those created using the multisport exercise mode on a Fitbit device.

Resource URL

GET https://api.fitbit.com/1/user/-/activities/list.json

URL parameters:

user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.
beforeDate The date in the format yyyy-MM-ddTHH:mm:ss. Only yyyy-MM-dd is required. Either beforeDate or afterDate must be specified. Set sort to desc when using beforeDate.
afterDate The date in the format yyyy-MM-ddTHH:mm:ss. Only yyyy-MM-dd is required. Either beforeDate or afterDate must be specified. Set sort to asc when using afterDate.
sort

The sort order of entries by date. Required.

Use asc (ascending) when using afterDate.

Use desc (descending) when using beforeDate.

limit The max of the number of entries returned (maximum: 20). Required.
offset

This should always be set to 0. Required for now.

IMPORTANT: To paginate, request the next and previous links in the pagination response object. Do not manually specify the offset parameter, as it will be removed in the future and your app will break.

Request Headers

Accept-Language optional The measurement unit system to use

Example Response

{
    "activities": [{
        "activeDuration": 1734000,
        "activityLevel": [{
            "minutes": 4,
            "name": "sedentary"
        }, {
            "minutes": 14,
            "name": "lightly"
        }, {
            "minutes": 4,
            "name": "fairly"
        }, {
            "minutes": 6,
            "name": "very"
        }],
        "activityName": "FitStar: Personal Trainer",
        "activityTypeId": 17589491,
        "averageHeartRate": 94,
        "calories": 136,
        "caloriesLink": "https://api.fitbit.com/1/user/-/activities/calories/date/2016-03-29/2016-03-29/1min/time/8:45/9:13.json",
        "distance": 1.071811,
        "distanceUnit": "Kilometer",
        "duration": 1734000,
        "heartRateLink": "https://api.fitbit.com/1/user/-/activities/heart/date/2016-03-29/2016-03-29/1sec/time/08:45:00/09:13:54.json",
        "heartRateZones": [{
            "max": 94,
            "min": 30,
            "minutes": 16,
            "name": "Out of Range"
        }, {
            "max": 131,
            "min": 94,
            "minutes": 9,
            "name": "Fat Burn"
        }, {
            "max": 159,
            "min": 131,
            "minutes": 1,
            "name": "Cardio"
        }, {
            "max": 220,
            "min": 159,
            "minutes": 0,
            "name": "Peak"
        }],
        "lastModified": "2016-03-29T17:41:53.000Z",
        "logId": 2067350363,
        "logType": "fitstar",
        "manualValuesSpecified": {
            "calories": false,
            "distance": false,
            "steps": false
        },
        "source": {
            "id": "228T4Z",
            "name": "FitStar",
            "type": "app",
            "url": "http://www.fitstar.com"
        },
        "speed": 2.2252131487889275,
        "startTime": "2016-03-29T08:45:00.000-07:00",
        "steps": 1354
    }, {
        "activeDuration": 1001000,
        "activityLevel": [{
            "minutes": 0,
            "name": "sedentary"
        }, {
            "minutes": 0,
            "name": "lightly"
        }, {
            "minutes": 17,
            "name": "fairly"
        }, {
            "minutes": 0,
            "name": "very"
        }],
        "activityName": "Bike",
        "activityTypeId": 90001,
        "averageHeartRate": 93,
        "calories": 77,
        "caloriesLink": "https://api.fitbit.com/1/user/-/activities/calories/date/2016-03-28/2016-03-28/1min/time/19:05/19:22.json",
        "distance": 4.1978,
        "distanceUnit": "Kilometer",
        "duration": 1001000,
        "heartRateLink": "https://api.fitbit.com/1/user/-/activities/heart/date/2016-03-28/2016-03-28/1sec/time/19:05:31/19:22:12.json",
        "heartRateZones": [{
            "max": 94,
            "min": 30,
            "minutes": 7,
            "name": "Out of Range"
        }, {
            "max": 131,
            "min": 94,
            "minutes": 10,
            "name": "Fat Burn"
        }, {
            "max": 159,
            "min": 131,
            "minutes": 0,
            "name": "Cardio"
        }, {
            "max": 220,
            "min": 159,
            "minutes": 0,
            "name": "Peak"
        }],
        "lastModified": "2016-03-29T03:03:12.000Z",
        "logId": 2068007929,
        "logType": "manual",
        "manualValuesSpecified": {
            "calories": true,
            "distance": true,
            "steps": true
        },
        "source": {
            "id": "22997K",
            "name": "Fitbit + Strava",
            "type": "app",
            "url": "https://strava.fitbit.com/"
        },
        "speed": 15.096983016983017,
        "startTime": "2016-03-28T19:05:31.000-07:00",
        "steps": 0
    }, {
        "activeDuration": 1503000,
        "activityLevel": [{
            "minutes": 4,
            "name": "sedentary"
        }, {
            "minutes": 11,
            "name": "lightly"
        }, {
            "minutes": 3,
            "name": "fairly"
        }, {
            "minutes": 7,
            "name": "very"
        }],
        "activityName": "Walk",
        "activityTypeId": 90013,
        "averageHeartRate": 96,
        "calories": 134,
        "caloriesLink": "https://api.fitbit.com/1/user/-/activities/calories/date/2016-03-26/2016-03-26/1min/time/14:49/15:14.json",
        "duration": 1503000,
        "heartRateLink": "https://api.fitbit.com/1/user/-/activities/heart/date/2016-03-26/2016-03-26/1sec/time/14:49:05/15:14:08.json",
        "heartRateZones": [{
            "max": 94,
            "min": 30,
            "minutes": 8,
            "name": "Out of Range"
        }, {
            "max": 131,
            "min": 94,
            "minutes": 17,
            "name": "Fat Burn"
        }, {
            "max": 159,
            "min": 131,
            "minutes": 0,
            "name": "Cardio"
        }, {
            "max": 220,
            "min": 159,
            "minutes": 0,
            "name": "Peak"
        }],
        "lastModified": "2016-03-26T22:34:17.000Z",
        "logId": 2047712815,
        "logType": "auto_detected",
        "manualValuesSpecified": {
            "calories": false,
            "distance": false,
            "steps": false
        },
        "startTime": "2016-03-26T14:49:05.000-07:00",
        "steps": 1662
    }, {
        "activeDuration": 2766000,
        "activityLevel": [{
            "minutes": 5,
            "name": "sedentary"
        }, {
            "minutes": 6,
            "name": "lightly"
        }, {
            "minutes": 2,
            "name": "fairly"
        }, {
            "minutes": 33,
            "name": "very"
        }],
        "activityName": "Workout",
        "activityTypeId": 3000,
        "averageHeartRate": 147,
        "calories": 416,
        "caloriesLink": "https://api.fitbit.com/1/user/-/activities/calories/date/2016-03-05/2016-03-05/1min/time/15:31/16:17.json",
        "duration": 2766000,
        "heartRateLink": "https://api.fitbit.com/1/user/-/activities/heart/date/2016-03-05/2016-03-05/1sec/time/15:31:17/16:17:23.json",
        "heartRateZones": [{
            "max": 94,
            "min": 30,
            "minutes": 3,
            "name": "Out of Range"
        }, {
            "max": 131,
            "min": 94,
            "minutes": 8,
            "name": "Fat Burn"
        }, {
            "max": 159,
            "min": 131,
            "minutes": 4,
            "name": "Cardio"
        }, {
            "max": 220,
            "min": 159,
            "minutes": 30,
            "name": "Peak"
        }],
        "lastModified": "2016-03-06T00:20:21.000Z",
        "logId": 1846159807,
        "logType": "tracker",
        "manualValuesSpecified": {
            "calories": false,
            "distance": false,
            "steps": false
        },
        "source": {
            "id": "47086726",
            "name": "Charge HR",
            "type": "tracker",
            "url": "https://www.fitbit.com/"
        },
        "startTime": "2016-03-05T15:31:17.000-08:00",
        "steps": 683,
        "tcxLink": "https://api.fitbit.com/1/user/-/activities/1846159807.json"
    }, {
        "activeDuration": 784739,
        "activityLevel": [{
            "minutes": 0,
            "name": "sedentary"
        }, {
            "minutes": 1,
            "name": "lightly"
        }, {
            "minutes": 0,
            "name": "fairly"
        }, {
            "minutes": 12,
            "name": "very"
        }],
        "activityName": "Run",
        "activityTypeId": 90009,
        "averageHeartRate": 125,
        "calories": 124,
        "caloriesLink": "https://api.fitbit.com/1/user/-/activities/calories/date/2016-01-31/2016-01-31/1min/time/19:11/19:24.json",
        "distance": 2.534752,
        "distanceUnit": "Kilometer",
        "duration": 784000,
        "heartRateLink": "https://api.fitbit.com/1/user/-/activities/heart/date/2016-01-31/2016-01-31/1sec/time/19:11:49/19:24:53.json",
        "heartRateZones": [{
            "max": 94,
            "min": 30,
            "minutes": 2,
            "name": "Out of Range"
        }, {
            "max": 131,
            "min": 94,
            "minutes": 1,
            "name": "Fat Burn"
        }, {
            "max": 159,
            "min": 131,
            "minutes": 10,
            "name": "Cardio"
        }, {
            "max": 220,
            "min": 159,
            "minutes": 0,
            "name": "Peak"
        }],
        "lastModified": "2016-02-01T03:25:03.000Z",
        "logId": 1546680089,
        "logType": "mobile_run",
        "manualValuesSpecified": {
            "calories": false,
            "distance": false,
            "steps": false
        },
        "pace": 309.30047594399764,
        "source": {
            "id": "2295XJ",
            "name": "Fitbit for Windows Phone",
            "type": "app",
            "url": "https://www.fitbit.com/"
        },
        "speed": 11.628206575689497,
        "startTime": "2016-01-31T19:11:49.000-08:00",
        "steps": 1827,
        "tcxLink": "https://api.fitbit.com/1/user/-/activities/1546680089.json"
    }, {
        "activeDuration": 6226000,
        "activityLevel": [{
            "minutes": 6,
            "name": "sedentary"
        }, {
            "minutes": 37,
            "name": "lightly"
        }, {
            "minutes": 28,
            "name": "fairly"
        }, {
            "minutes": 32,
            "name": "very"
        }],
        "activityName": "Hike",
        "activityTypeId": 90012,
        "averageHeartRate": 102,
        "calories": 582,
        "caloriesLink": "https://api.fitbit.com/1/user/-/activities/calories/date/2015-05-25/2015-05-25/1min/time/14:08/16:09.json",
        "distance": 5.600688,
        "distanceUnit": "Kilometer",
        "duration": 7272000,
        "heartRateLink": "https://api.fitbit.com/1/user/-/activities/heart/date/2015-05-25/2015-05-25/1sec/time/14:08:12/16:09:24.json",
        "heartRateZones": [{
            "max": 94,
            "min": 30,
            "minutes": 24,
            "name": "Out of Range"
        }, {
            "max": 132,
            "min": 94,
            "minutes": 79,
            "name": "Fat Burn"
        }, {
            "max": 160,
            "min": 132,
            "minutes": 0,
            "name": "Cardio"
        }, {
            "max": 220,
            "min": 160,
            "minutes": 0,
            "name": "Peak"
        }],
        "lastModified": "2015-07-15T23:45:47.000Z",
        "logId": 228167717,
        "logType": "tracker",
        "manualValuesSpecified": {
            "calories": false,
            "distance": false,
            "steps": false
        },
        "pace": 1111.6491402484837,
        "source": {
            "id": "18834976",
            "name": "Surge",
            "type": "tracker",
            "url": "https://www.fitbit.com/"
        },
        "speed": 3.2384318663668488,
        "startTime": "2015-05-25T14:08:12.000-07:00",
        "steps": 7295,
        "tcxLink": "https://api.fitbit.com/1/user/-/activities/228167717.json"
    }],
    "pagination": {
        "beforeDate": "2016-03-30",
        "limit": 10,
        "next": "https://api.fitbit.com/1/user/-/activities/list.json?limit=10&sort=desc&beforeDate=2015-07-15T23:45:47.000Z",
        "sort": "desc"
    }
}

Get Activity TCX

Note: Since this is a beta feature, Fitbit may need to make backwards incompatible changes with less than 30 days notice.

The Get Activity TCX endpoint retrieves the details of a user's location and heart rate data during a logged exercise activity.

The Training Center XML (TCX) is a data exchange format that contains GPS, heart rate, and lap data, when it is available for the activity. The TCX MIME type is application/vnd.garmin.tcx+xml.

TCX requires GPS data and heart data points, which are tied to GPS data points. If you only want heart rate, see the heart rate intraday time series.

Resource URLs

GET https://api.fitbit.com/1/user/[user-id]/activities/[log-id].tcx
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.
log-id The activity's log ID.

Finding an "activity's log id"

Go to the Activity Logs page in the Fitbit Web app. Click View Details button on the Activity History pane that contains GPS data. The activity log id will be in the URL, e.g. 213560689 in https://www.fitbit.com/activities/exercise/213560689 . The GPS activities appears in the Get Activities and Get Activities List endpoints contains GPS activities.

Activity Types

Browse Activity Types

Get a tree of all valid Fitbit public activities from the activities catalog as well as private custom activities the user created in the format requested. If the activity has levels, also get a list of activity level details.

Typically, an applications retrieve the complete list of activities once at startup to cache and show in the UI later.

Resource URLs

GET https://api.fitbit.com/1/activities.json

Get Activity Type

Returns the details of a specific activity in the Fitbit activities database in the format requested. If activity has levels, also returns a list of activity level details.

Resource URLs

GET https://api.fitbit.com/1/activities/[activity-id].json
activity-id The activity ID.

Request Headers

Accept-Locale optional The measurement unit system to use for response values.

Example Response

{
    "activity": {
        "accessLevel":"PUBLIC",
        "activityLevels":[
            {
                "id":1010,
                "maxSpeedMPH":9.9,
                "minSpeedMPH":-1,
                "mets":4,
                "name":"Very Leisurely - Less than 10 mph"
            },
            {
                "id":1020,
                "maxSpeedMPH":11.9,
                "minSpeedMPH":10,
                "mets":6,
                "name":"Leisurely - 10 to 11.9mph"
            },
            {
                "id":1030,
                "maxSpeedMPH":13.9,
                "minSpeedMPH":12,
                "mets":8,
                "name":"Moderate - 12 to 13.9mph"
            },
            {
                "id":1009,
                "maxSpeedMPH":-1,
                "minSpeedMPH":-1,
                "mets":8.5,
                "name":"Mountain Biking/BMX"
            },
            {
                "id":1040,
                "maxSpeedMPH":15.9,
                "minSpeedMPH":14,
                "mets":10,
                "name":"Fast - 14 to 15.9mph"
            },
            {
                "id":1050,
                "maxSpeedMPH":19,
                "minSpeedMPH":16,
                "mets":12,
                "name":"Really Fast - 16 to 19mph"
            },
            {
                "id":1060,
                "maxSpeedMPH":-1,
                "minSpeedMPH":20,
                "mets":16,
                "name":"Racing - Faster than 20mph"
            }
        ],
        "hasSpeed":true,
        "id":90001,
        "name":"Bicycling"
    }
}

Get Frequent Activities

The Get Frequent Activities endpoint retrieves a list of a user's frequent activities in the format requested using units in the unit system which corresponds to the Accept-Language header provided. A frequent activity record contains the distance and duration values recorded the last time the activity was logged. The record retrieved can be used to log the activity via the Log Activity endpoint with the same or adjusted values for distance and duration.

Resource URLs

GET https://api.fitbit.com/1/user/-/activities/frequent.json

Request Headers

Accept-Locale optional The locale to use for response values.
Accept-Language optional The measurement unit system to use for response values.

Example Response

[
    {
        "activityId":1030,
        "calories":1721,
        "description":"Moderate - 12 to 13.9mph",
        "distance":1,
        "duration":3723000,
        "name":"Bicycling"
    },
    {
        "activityId":12030,
        "calories":1124,
        "description":"Running - 5 mph (12 min/mile)",
        "distance":2,
        "duration":7322000,
        "name":"Running"
    },
    {
        "activityId":18240,
        "calories":1476,
        "description":"",
        "distance":0,
        "duration":10983000,
        "name":"Swimming laps, freestyle, slow, moderate or light effort"
    },
    {
        "activityId":17151,
        "calories":357,
        "description":"Walking less than 2 mph, strolling very slowly",
        "distance":4,
        "duration":3723000,
        "name":"Walking"
    },
    {
        "activityId":18120,
        "calories":1291,
        "description":"",
        "distance":0,
        "duration":3723000,
        "name":"Sailing, boat and board sailing, windsurfing, ice sailing, general"
    }
]

Get Recent Activity Types

The Get Recent Activity Types endpoint retrieves a list of a user's recent activities types logged with some details of the last activity log of that type using units in the unit system which corresponds to the Accept-Language header provided. The record retrieved can be used to log the activity via the Log Activity endpoint with the same or adjusted values for distance and duration.

Resource URLs

GET https://api.fitbit.com/1/user/-/activities/recent.json

Request Headers

Accept-Locale The locale to use for response values.
Accept-Language optional The measurement unit system to use for response values.

Example Response

[
    {
        "activityId":1030,
        "calories":1721,
        "description":"Moderate - 12 to 13.9mph",
        "distance":1,
        "duration":3723000,
        "name":"Bicycling"
    },
    {
        "activityId":12030,
        "calories":1124,
        "description":"Running - 5 mph (12 min/mile)",
        "distance":2,
        "duration":7322000,
        "name":"Running"
    },
    {
        "activityId":18240,
        "calories":1476,
        "description":"",
        "distance":0,
        "duration":10983000,
        "name":"Swimming laps, freestyle, slow, moderate or light effort"
    },
    {
        "activityId":17151,
        "calories":357,
        "description":"Walking less than 2 mph, strolling very slowly",
        "distance":4,
        "duration":3723000,
        "name":"Walking"
    },
    {
        "activityId":18120,
        "calories":1291,
        "description":"",
        "distance":0,
        "duration":3723000,
        "name":"Sailing, boat and board sailing, windsurfing, ice sailing, general"
    }
]

Get Favorite Activities

The Get Favorite Activities endpoint returns a list of a user's favorite activities.

Resource URLs

GET https://api.fitbit.com/1/user/[user-id]/activities/favorite.json
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.

Example Response

[
   {
    "activityId": 12030,
    "description": "5 mph (12 min/mile)",
    "mets": 8,
    "name": "Run"
  }
]

Add Favorite Activity

The Add Favorite Activity endpoint adds the activity with the given ID to user's list of favorite activities.

Resource URLs

POST https://api.fitbit.com/1/user/-/activities/favorite/[activity-id].json
activity-id The ID of the activity to add to user's favorites.

Note: A successful request returns a 201 response code with an empty body.

Delete Favorite Activity

The Delete Favorite Activity removes the activity with the given ID from a user's list of favorite activities.

Resource URLs

DELETE https://api.fitbit.com/1/user/-/activities/favorite/[activity-id].json
activity-id The ID of the activity to be removed.

Note: A successful request returns a 204 status code with an empty response body.

Activity Goals

Get Activity Goals

The Get Activity Goals retrieves a user's current daily or weekly activity goals using measurement units as defined in the unit system, which corresponds to the Accept-Language header provided.

Considerations

  1. Only the current goals are returned.

  2. Floors goal only returned for users who currently or have previously paired a Fitbit device with an altimeter.

  3. Calories out goal represents either dynamic daily target from the Premium trainer plan or manual calorie burn goal.

The default daily goal values are:

  • 10 floors
  • 30 active minutes
  • Calories out is user specific, which accounts for BMR

Resource URLs

GET https://api.fitbit.com/1/user/[user-id]/activities/goals/[period].json
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.
period daily or weekly

Request Headers

Accept-Language optional The measurement unit system to use for response values.

Example Response

{
    "goals":{
        "caloriesOut": 2500,
        "distance": 8.05,
        "floors": 10,
        "steps": 10000
    }
}

Update Activity Goals

The Update Activity Goals endpoint creates or updates a user's daily activity goals and returns a response using units in the unit system which corresponds to the Accept-Language header provided.

Resource URLs

POST https://api.fitbit.com/1/user/[user-id]/activities/goals/[period].json
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.
period daily or weekly

Request Headers

Accept-Language optional The measurement unit system to use for response values.

POST Parameters

caloriesOut optional Goal value; integer.
activeMinutes optional Goal value; integer.
floors optional Goal value; integer.
distance optional Goal value; in the format X.XX or integer.
steps optional Goal value; integer.

Example Response

{
    "goals":{
        "caloriesOut": 2500,
        "distance": 8.05,
        "floors": 15,
        "steps": 10000
    }
}

Get Lifetime Stats

The Get Lifetime Stats endpoint retrieves the user's activity statistics in the format requested using units in the unit system which corresponds to the Accept-Language header provided. Activity statistics includes Lifetime and Best achievement values from the My Achievements tile on the website dashboard. Response contains both statistics from the tracker device and total numbers including tracker data and manual activity log entries as seen on the Fitbit website dashboard.

Privacy Setting

The My Achievements (Friends or Anyone) privacy permission grants access to user's resource.

Resource URLs

GET https://api.fitbit.com/1/user/[user-id]/activities.json
user-id The encoded ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-Language optional The measurement unit system to use for response values.

Example Response

{
    "best":{
        "total":{
           "distance":{
                "date":"2012-01-07",
                "value":20.31597
            },
            "floors":{
                "date":"2012-01-29",
                "value":14
            },
            "steps":{
                "date":"2012-01-07",
                "value":26901
            }
        },
        "tracker":{
            "distance":{
                "date":"2012-01-07",
                "value":20.31597
            },
            "floors":  {
                 "date":"2012-01-29",
                 "value":14
            },
            "steps":{
                 "date":"2012-01-07",
                 "value":26901
            }
        }
    },
    "lifetime":{
        "total":{
            "distance":2711.62,
            "floors":2500,
            "steps":203300
        },
        "tracker":{
            "distance":2579.82,
            "floors":2500,
            "steps":106934
        }
     }
}