Retrieving Collection Data

Get Food Locales

The Get Food Locales endpoint returns the food locales that the user may choose to search, log, and create food in.

Notes

The values returned from Food Locales endpoint may be specified in any other Food API calls on the query string parameter foodDatabase for instance https://api.fitbit.com/1/user/-/foods.json?foodDatabase=es_MX to create food in the Mexican locale.

Resource URL

GET https://api.fitbit.com/1/foods/locales.json

Response Body Format and Example

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

Body Format:

[
   {
    "barcode": <true or false if the locale supports search by barcode>,
    "label": <Human readable UI label>,
    "value": <Locale name>
  }, ...
]

Example of Food Locales Response:

[ 
   {
    "barcode": true,
    "label": "Deutschland",
    "value": "de_DE"
  },
   {
    "barcode": true,
    "label": "France",
    "value": "fr_FR"
  },
   {
    "barcode": true,
    "label": "España",
    "value": "es_ES"
  },
   {
    "barcode": true,
    "label": "United Kingdom",
    "value": "en_GB"
  },
   {
    "barcode": true,
    "label": "United States",
    "value": "en_US"
  },
   {
    "barcode": false,
    "label": "日本",
    "value": "ja_JP"
  },
   {
    "barcode": true,
    "label": "Australia",
    "value": "en_AU"
  },
   {
    "barcode": true,
    "label": "Canada",
    "value": "en_CA"
  },
   {
    "barcode": true,
    "label": "Italia",
    "value": "it_IT"
  },
   {
    "barcode": true,
    "label": "한국",
    "value": "ko_KR"
  },
   {
    "barcode": true,
    "label": "México",
    "value": "es_MX"
  }
]

Get Food Goals

The Get Food Goals endpoint returns a user's current daily calorie consumption goal and/or food Plan in the format requested.

Considerations

  1. If the Food Plan feature is not enabled, then the foodPlan value is not included.
  2. The calories value consists of either manual calorie target or the user's calorie goal according to their Food Plan, where the Food Plan is enabled.
  3. Estimated calorie consumption for the day is retrieved via the "Get Activities" endpoint.

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/foods/log/goal.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.

Response Body Format and Example

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

Body Format:

{
    "goals":{
        "calories":<value>
    },
    "foodPlan":{
        "intensity":<value>,
        "estimatedDate":<value>,
        "personalized":<value>
    }
}

Example of Food Goals Response:

{
    "goals":{
        "calories":1800
    },
    "foodPlan":{
        "intensity":"MEDIUM",
        "estimatedDate":"2014-12-31",
        "personalized":true
    }
}

Get Food Logs

The Get Food Logs endpoint returns a summary and list of a user's food log entries for a given day in the format requested.

Access Levels

There are three access level types for food log entries that an authorized user can view via API requests. Each food is annotated with an accessLevel field with one of the following values:

  • PUBLIC - Foods that are in Fitbit's public food database and are visible to any Fitbit users. Only Fitbit populates this database to avoid spam and duplicate entries.
  • PRIVATE - Foods created by a user either on the website or via the Create Food endpoint.
  • SHARED - A food created by a user whose foods privacy is set to Friends or Anyone. These can be logged either on the website or via the Log Food endpoint. These foods can be discovered using the Search Foods endpoint.

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/foods/log/date/[date].json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
dateThe date of records to be returned. In the format yyyy-MM-dd.

Example Request

GET https://api.fitbit.com/1/user/28H22H/foods/log/date/2015-09-01.json

Request Headers

Accept-LanguageoptionalUsed to determine the food measurement units returned.

Response Body Format and Example

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

Body Format:

{
    "foods":[
        {
            "isFavorite":<value>,
            "logDate":<value>,
            "logId":<value>,
            "loggedFood":{
                "accessLevel":<value>,
                "amount":<value>,
                "brand":<value>,
                "calories":<value>,
                "foodId":<value>,
                "mealTypeId":<value>,
                "locale":<value>,
                "name":<value>,
                "unit":{"id":<value>,"name":<value>,"plural":<value>},
                "units":[<value>,..,<value>]
            },
            "nutritionalValues":{
                "calories":<value>,
                "carbs":<value>,
                "fat":<value>,
                "fiber":<value>,
                "protein":<value>,
                "sodium":<value>
            }
        },
        <...>
    ],
    "summary":{
        "calories":<value>,
        "carbs":<value>,
        "fat":<value>,
        "fiber":<value>,
        "protein":<value>,
        "sodium":<value>,
        "water":<value>
    },
    "goals":{
        "calories":<value>,
        "estimatedCaloriesOut":<value>
    }
}

Example of Food Log Response:

{
    "foods":[
        {
            "isFavorite":true,
            "logDate":"2011-06-29",
            "logId":1820,
            "loggedFood":{
                "accessLevel":"PUBLIC",
                "amount":132.57,
                "brand":"",
                "calories":752,
                "foodId":18828,
                "mealTypeId":4,
                "locale":"en_US",
                "name":"Chocolate, Milk",
                "unit":{
                    "id":147,
                    "name":"gram",
                    "plural":"grams"
                },
                "units":[226,180,147,389]
            },
            "nutritionalValues":{
                "calories":752,
                "carbs":66.5,
                "fat":49,
                "fiber":0.5,
                "protein":12.5,
                "sodium":186
            }
        }
    ],
    "summary":{
        "calories":752,
        "carbs":66.5,
        "fat":49,
        "fiber":0.5,
        "protein":12.5,
        "sodium":186,
        "water":0
    },
    "goals":{
        "calories": 2286
    }
}

Get Water Logs

The Get Water Logs endpoint retrieves a summary and list of a user's water log entries for a given day in the format requested using units in the unit system that corresponds to the Accept-Language header provided. Water log entries are available only to an authorized user. If you need to fetch only total amount of water consumed, you can use the Get Food endpoint. Water log entries in response are sorted exactly the same as they are presented on the Fitbit website.

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/foods/log/water/date/[date].json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
dateThe date of records to be returned. In the format yyyy-MM-dd.

Example Request

GET https://api.fitbit.com/1/user/-/foods/log/water/date/2015-09-01.json

Request Headers

Accept-LanguageoptionalUsed to determine the food measurement units returned.

Response Body Format and Example

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

Body Format:

{
    "summary":{
       "water":<value>
    },
    "water":[
        {"logId":<value>,"amount":<value>},
        <...>
    ]
}

Example of Water Log Response:

{
    "summary":{
       "water":800;
    },
    "water":[
        {"amount":500,"logId":950},
        {"amount":200,"logId":951},
        {"amount":100,"logId":952}
    ]
}

Get Water Goal

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/foods/log/water/goal.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.

Response Body Format and Example

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

Example of Water Log Response:

{
    "goal": {
        "goal": 1892,
        "startDate": "2015-05-15""
    }
}

Food or Water Time Series

Get Food or Water Time Series

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

Note: 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.

Resource URL

There are two accepted formats for retrieving intraday data:

1) GET https://api.fitbit.com/1/user/[user-id]/[resource-path]/date/[date]/[period].json

api-versionThe API version. Currently version 1.
user-idThe encoded ID of the user. Use "-" (dash) for current logged-in user.
resource-pathThe resource path; see options in the "Resource Path Options" section below.
dateThe end date of the period specified in the format yyyy-MM-dd or today.
periodThe range for which data will be returned. Options are 1d, 7d, 30d, 1w, 1m, 3m, 6m, 1y


2) GET https://api.fitbit.com/1/user/[user-id]/[resource-path]/date/[base-date]/[end-date].json

api-versionThe API version. Currently version 1.
user-idThe encoded ID of the user. Use "-" (dash) for current logged-in user.
resource-pathThe resource path; see options in the "Resource Path Options" section below.
base-dateThe range start date, in the formatyyyy-MM-dd or today.
end-dateThe end date of the range.

Resource Path Options

foods/log/caloriesIn    
foods/log/water

Example Request

GET https://api.fitbit.com/1/user/-/foods/log/caloriesIn/date/2015-09-01/2015-09-05.json

Request Headers

Accept-LanguageoptionalThe language used for response values. Language is used to determine the food measurement units returned.

Logging and Deleting Collection Data

Approaches to Logging Food

There are two scenarios for creating food log entries for the user - with or without foodId value. The common approach is to use foodId and create the entry with a link to the food from the Food DB (Search Foods) or to the user's private food (Create Food). Fitbit recommends each integration use this first approach, when possible.

The second approach is used if you want just to upload some history data or to log a daily intake summary only (or several specific meal's summaries) for the user the foodName parameter might be helpful. In this case, you should also explicitly provide the calories and optionally brandName (or source name) and a full set of nutritional values for this log entry. Entries logged via foodName can not be edited on the website or added to the list of favorites.

Considerations

  1. The units field contains references to respective "Food Units".
  2. The accessLevel field can be PUBLIC, PRIVATE, or SHARED.

Resource URL

POST https://api.fitbit.com/1/user/[user-id]/foods/log.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-LanguageoptionalThe measurement unit system to use for POST parameters and response values.

POST Parameters

foodIdoptional/requiredID of the food to be logged. Either foodId or foodName must be provided.
foodNameoptional/requiredFood entry name. Either foodId or foodName must be provided.
mealTypeIdrequiredMeal type. 1=Breakfast; 2=Morning Snack; 3=Lunch; 4=Afternoon Snack; 5=Dinner; 7=Anytime.
unitIdrequiredID of units used. Typically retrieved via a previous call to Get Food Logs, Search Foods, or Get Food Units.
amountrequiredAmount consumed; in the format X.XX, in the specified unitId.
daterequiredLog entry date; in the format yyyy-MM-dd.
favoriteoptionaltrue will add the food to the user's favorites after creating the log entry; false will not. Valid only with foodId.
brandNameoptionalBrand name of food. Valid only with foodName parameter.
caloriesoptionalCalories for this serving size. Allowed with foodName parameter (defaults to zero); otherwise ignored.

Additional Nutrition Information (optional and valid only with foodName)

CommonVitaminsDietary Minerals
caloriesFromFat
totalFat(g)
transFat(g)
saturatedFat(g)
cholesterol(mg)
sodium(mg)
potassium(mg)
totalCarbohydrate(g)
dietaryFiber(g)
sugars(g)
protein(g)
vitaminA(IU)
vitaminB6
vitaminB12
vitaminC(mg)
vitaminD(IU)
vitaminE(IU)
biotin(mg)
folicAcid(mg)
niacin(mg)
pantothenicAcid(mg)
riboflavin(mg)
thiamin(mg)
calcium(g)
copper(g)
iron(mg)
magnesium(mg)
phosphorus(g)
iodine(mcg)
zinc(mg)

Response Body Format and Example

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

Body Format:

{
    "foodLog":{
        "isFavorite":<value>,
        "logDate":<value>,
        "logId":<value>,
        "loggedFood":{
            "accessLevel":<value>,
            "amount":<value>,
            "brand":<value>,
            "calories":<value>,
            "foodId":<value>,
            "mealTypeId":<value>,
            "locale":<value>,
            "name":<value>,
            "unit":{
                "id":<value>,
                "name":<value>,
                "plural":<value>
            },
            "units":[
                <value>,
                ...,
                <value>
            ]
        },
        "nutritionalValues":{
            "calories":<value>,
            "carbs":<value>,
            "fat":<value>,
            "fiber":<value>,
            "protein":<value>,
            "sodium":<value>
        }
    }
}

Example of Response:

{
    "foodLog":{
        "isFavorite":true,
        "logDate":"2011-06-29",
        "logId":21633,
        "loggedFood":{
            "accessLevel":"PUBLIC",
            "amount":2.55,
            "brand":"",
            "calories":370,
            "foodId":82294,
            "mealTypeId":7,
            "locale":"en_US",
            "name":"Chips",
            "unit":{"id":304,"name":"serving","plural":"servings"},
            "units":[304,226,180,147,389]
        },
        "nutritionalValues":{
            "calories":370,
            "carbs":47,
            "fat":17.5,
            "fiber":5,
            "protein":5,
            "sodium":325
        }
    }
}

Editing Food Logs

The Edit Food Log endpoint changes the quantity or calories consumed for a user's food log entry with the given ID.

Resource URL

POST https://api.fitbit.com/1/user/[user-id]/foods/log/[food-log-id].json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
food-log-idThe ID of the food log to edit

Request Headers

Accept-LanguageoptionalThe measurement unit system to use for POST parameters and response values.

POST Parameters

mealTypeIdrequiredMeal type. 1=Breakfast; 2=Morning Snack; 3=Lunch; 4=Afternoon Snack; 5=Dinner; 7=Anytime.
unitIdoptional/requiredID of units used. Not required if the food log was created with the foodName parameter. Typically retrieved via a previous call to Get Food Logs, Search Foods, or Get Food Units.
amountoptional/requiredAmount consumed; Not required if the food log was created with the foodName parameter. In the format X.XX, in the specified unitId.
caloriesoptional/requiredCalories for this food log. Allowed if the food log was created with the foodName parameter (defaults to zero); otherwise ignored.

Response Body Format and Example

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

Body Format:

{
    "foodLog":{
        "isFavorite":<value>,
        "logDate":<value>,
        "logId":<value>,
        "loggedFood":{
            "accessLevel":<value>,
            "amount":<value>,
            "brand":<value>,
            "calories":<value>,
            "foodId":<value>,
            "mealTypeId":<value>,
            "locale":<value>,
            "name":<value>,
            "unit":{
                "id":<value>,
                "name":<value>,
                "plural":<value>
            },
            "units":[
                <value>,
                ...,
                <value>
            ]
        },
        "nutritionalValues":{
            "calories":<value>,
            "carbs":<value>,
            "fat":<value>,
            "fiber":<value>,
            "protein":<value>,
            "sodium":<value>
        }
    }
}

Example of Response:

{
    "foodLog":{
        "isFavorite":true,
        "logDate":"2011-06-29",
        "logId":21633,
        "loggedFood":{
            "accessLevel":"PUBLIC",
            "amount":2.55,
            "brand":"",
            "calories":370,
            "foodId":82294,
            "mealTypeId":7,
            "locale":"en_US",
            "name":"Chips",
            "unit":{"id":304,"name":"serving","plural":"servings"},
            "units":[304,226,180,147,389]
        },
        "nutritionalValues":{
            "calories":370,
            "carbs":47,
            "fat":17.5,
            "fiber":5,
            "protein":5,
            "sodium":325
        }
    }
}

Log Water

This endpoint creates a log entry for water using units in the unit systems that corresponds to the Accept-Language header provided.

Resource URL

POST https://api.fitbit.com/1/user/[user-id]/foods/log/water.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
dateThe date of records to be returned. In the format yyyy-MM-dd.

Request Headers

Accept-LanguageoptionalThe measurement unit system to use for POST parameters and response values.

POST Parameters

amountrequiredAmount consumed; in the format X.X and in the specified waterUnit or in the unit system that corresponds to the Accept-Language header provided.
daterequiredLog entry date; in the format yyyy-MM-dd.
unitoptionalWater measurement unit. "ml", "fl oz", or "cup".

Response Body Format and Example

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

Body Format:

{
    "waterLog":{
       "logId":<value>,
       "amount":<value>
    }
}

Example of Water Log Response:

{
    "waterLog":{
       "logId":154654,
       "amount":300
    }
}

Update Food Goal

The Update Food Goal endpoint updates or creates a user's daily calorie consumption goal or food plan and returns a response in the format requested. Food plan exists only if user already as an active weight goal crated via the Update Weight Goal endpoint.

Resource URL

POST https://api.fitbit.com/1/user/[user-id]/foods/log/goal.json

user-idThe ID of the user. Use "-" for current logged-in user.

Request Headers

Accept-LocaleoptionalThe locale to use for response values.
Accept-LanguageoptionalThe measurement unit system to use for POST parameters and response values.

Example Request

POST https://api.fitbit.com/1/user/28H22H/foods/log/goal.json

POST Parameters

caloriesoptional/requiredManual calorie consumption goal in integer format. Either calories or intensity must be provided.
intensityoptional/requiredFood plan intensity (MAINTENANCE, EASIER, MEDIUM, KINDAHARD, or HARDER). Either calories or intensity must be provided.
personalizedoptionalFood plan type; true or false.

Example Response

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

{
    "goals":{
        "calories":1800
    },
    "foodPlan":{
        "intensity":"MEDIUM",
        "estimatedDate":"2012-12-31",
        "personalized":true
    }
}

Update Water Goal

The Update WaterGoal endpoint updates or creates a user's daily calorie consumption goal or food plan and returns a response in the format requested. Food plan exists only if user already as an active weight goal created via the Update Weight Goal endpoint.

Resource URL

POST https://api.fitbit.com/1/user/[user-id]/foods/log/water/goal.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.

POST Parameters

targetrequiredTarget water goal in the format X.X is set in unit based on locale

Example Response

{
    "goal":15
}

Delete Food Log

The Delete Food Log endpoint deletes a user's food log entry with the given ID.

Resource URL

DELETE https://api.fitbit.com/1/user/[user-id]/foods/log/[food-log-id].json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
food-log-idThe id of the food log entry to be deleted.

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

Update Water Log

Resource URL

POST https://api.fitbit.com/1/user/[user-id]/foods/log/water/[water-log-id].json

Request Headers

Accept-LanguageoptionalThe measurement unit system to use for POST parameters and response values.

POST Parameters

amountrequiredAmount consumed; in the format X.X and in the specified waterUnit or in the unit system that corresponds to the Accept-Language header provided.
unitoptionalWater measurement unit. "ml", "fl oz", or "cup".

Example

Example of Water Log Response:

{
    "waterLog":{
       "logId":1543654,
       "amount":400
    }
}

Delete Water Log

The Delete Water Log endpoint deletes a user's water log entry with the given ID.

Resource URL

DELETE https://api.fitbit.com/1/user/[user-id]/foods/log/water/[water-log-id].json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
water-log-idThe id of the water log entry to be deleted.

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

Collection Metadata

Get Favorite Foods

This endpoint returns a list of a user's favorite foods in the format requested. A favorite food in the list provides a quick way to log the food via the Log Food endpoint.

Access Levels

There are three access level types for food log entries that an authorized user can view via API requests. Each food is annotated with an accessLevel field with one of the following values:

  • PUBLIC - Foods that are in Fitbit's public food database and are visible to any Fitbit users. Only Fitbit populates this database to avoid spam and duplicate entries.
  • PRIVATE - Foods created by a user either on the website or via the Create Food endpoint.
  • SHARED - A food created by a user whose foods privacy is set to Friends or Anyone. These can be logged either on the website or via the Log Food endpoint. These foods can be discovered using the Search Foods endpoint.

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/foods/log/favorite.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-LanguageoptionalUsed to determine the food measurement units returned.

Example Response

[
    {
        "accessLevel":"PRIVATE",
        "brand":"Philadelphia Brand",
        "calories":60,
        "defaultServingSize":2,
        "defaultUnit":{"id":349,"name":"tbsp","plural":"tbsp"},
        "foodId":12323,
        "name":"Cream Cheese, Ranch, Whipped",
        "servings":[
            {
                "multiplier":1,
                "servingSize":2,
                "unitId":349
                "unit":{"id":349,"name":"tbsp","plural":"tbsp"},
            },
            {
                "multiplier":1,
                "servingSize":0.7400000095367432,
                "unitId":226
            }
        ],
        "units":[349,364,226,180,147,389],
        "nutritionalValues":
                {
                    "biotin":0,
                    "calcium":0,
                    "calories":60,
                    "caloriesFromFat":52,
                    "cholesterol":15,
                    "copper":0,
                    "dietaryFiber":0,
                    "folicAcid":0,
                    "iodine":0,
                    "iron":0,
                    "magnesium":0,
                    "niacin":0,
                    "pantothenicAcid":0,
                    "phosphorus":0,
                    "potassium":0,
                    "protein":1,
                    "riboflavin":0,
                    "saturatedFat":3.5,
                    "sodium":150,
                    "sugars":1,
                    "thiamin":0,
                    "totalCarbohydrate":1,
                    "totalFat":6,
                    "transFat":0,
                    "vitaminA":300,
                    "vitaminB12":0,
                    "vitaminB6":0,
                    "vitaminC":0,
                    "vitaminD":0,
                    "vitaminE":0,
                    "zinc":0
                }    
    }
]

Get Frequent Foods

This endpoint returns a list of a user's frequent foods in the format requested. A frequent food in the list provides a quick way to log the food via the Log Food endpoint.

Access Levels

There are three access level types for food log entries that an authorized user can view via API requests. Each food is annotated with an accessLevel field with one of the following values:

  • PUBLIC - Foods that are in Fitbit's public food database and are visible to any Fitbit users. Only Fitbit populates this database to avoid spam and duplicate entries.
  • PRIVATE - Foods created by a user either on the website or via the Create Food endpoint.
  • SHARED - A food created by a user whose foods privacy is set to Friends or Anyone. These can be logged either on the website or via the Log Food endpoint. These foods can be discovered using the Search Foods endpoint.

Considerations

  1. The units field contains references to respective Food Units.
  2. The accessLevel field can be PUBLIC, PRIVATE, or SHARED.

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/foods/log/frequent.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-LanguageoptionalUsed to determine the food measurement units returned.

Example Response

[
    {
        "accessLevel":"PRIVATE",
        "amount":1,
        "brand":"",
        "calories":59,
        "foodId":25868,
        "mealTypeId":7,
        "name":"Papaya, Raw",
        "unit":{"id":319,"name":"small","plural":"smalls"},
        "units":[319,204,179,91,256,279,226,180,147,389]
    },
    {
        "accessLevel":"PUBLIC",
        "amount":1,
        "brand":"",
        "calories":154,
        "foodId":1182,
        "mealTypeId":7,
        "locale":"en_US",
        "name":"Yogurt, Lowfat",
        "unit":{"id":91,"name":"cup","plural":"cups"},
        "units":[91,256,279,226,180,147,389]
    }
]

Get Recent Foods

The Get Recent Foods endpoint returns a list of a user's recent foods in the format requested. A recent food provides a quick way to log the food via the Log Food endpoint.

Considerations

  1. The units field contains references to respective Food Units.
  2. The accessLevel field can be PUBLIC, PRIVATE, or SHARED.

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/foods/recent.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-LanguageoptionalUsed to determine the food measurement units returned.

Example Response

[
    {
        "accessLevel":"PRIVATE",
        "amount":1,
        "brand":"",
        "calories":59,
        "foodId":25868,
        "mealTypeId":7,
        "name":"Papaya, Raw",
        "unit":{"id":319,"name":"small","plural":"smalls"},
        "units":[319,204,179,91,256,279,226,180,147,389]
    },
    {
        "accessLevel":"PUBLIC",
        "amount":1,
        "brand":"",
        "calories":154,
        "foodId":1182,
        "mealTypeId":7,
        "locale":"en_US",
        "name":"Yogurt, Lowfat",
        "unit":{"id":91,"name":"cup","plural":"cups"},
        "units":[91,256,279,226,180,147,389]
    }
]

Add Favorite Food

The Add Favorite Food endpoint adds a food with the given ID to the user's list of favorite foods.

Resource URL

POST https://api.fitbit.com/1/user/[user-id]/foods/log/favorite/[food-id].json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
food-idThe ID of the food to be added to user's favorites.

A successful requests returns a 201 status code and an empty response body.

Delete Favorite Food

The Delete Favorite Food endpoint deletes a food with the given ID to the user's list of favorite foods.

Resource URL

DELETE https://api.fitbit.com/1/user/[user-id]/foods/log/favorite/[food-id].json

Removes a food with the given ID from the user's list of favorite foods.

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
food-idThe ID of the food to be removed.

A successful request returns a 204 status code and an empty response body.

Get Meals

This endpoint returns a list of meals created by user in his or her food log in the format requested. Meals in the list provide a quick way to log several foods at a time via the calls to the Log Food endpoint.

Access Levels

There are three access level types for food log entries that an authorized user can view via API requests. Each food is annotated with an accessLevel field with one of the following values:

  • PUBLIC - Foods that are in Fitbit's public food database and are visible to any Fitbit users. Only Fitbit populates this database to avoid spam and duplicate entries.
  • PRIVATE - Foods created by a user either on the website or via the Create Food endpoint.
  • SHARED - A food created by a user whose foods privacy is set to Friends or Anyone. These can be logged either on the website or via the Log Food endpoint. These foods can be discovered using the Search Foods endpoint.

Considerations

  1. The units field contains references to respective Food Units.
  2. The accessLevel field can be PUBLIC, PRIVATE, or SHARED.
  3. The mealTypeId field is always 7 (Anytime.) Meals are not associated with particular times.

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/meals.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-LanguageoptionalUsed to determine the food measurement units returned.

Example Response

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

{
    "meals":[
       <meal>, 
       <...> 
    ]
}
Example meal
{
            "mealFoods":[
                {
                    "accessLevel":"PUBLIC",
                    "amount":1,
                    "brand":"Dannon",
                    "calories":15,
                    "foodId":33893,
                    "mealTypeId":7,
                    "locale":"en_US",
                    "name":"Yogurt, Dan-o-nino, Banana",
                    "unit":{"id":91,"name":"cup","plural":"cups"},
                    "units":[91,256,279,226,180,147,389]
                },
                {
                    "accessLevel":"PUBLIC",
                    "amount":16,
                    "brand":"",
                    "calories":9,
                    "foodId":17222,
                    "mealTypeId":7,
                    "locale":"en_US",
                    "name":"Coffee",
                    "unit":{"id":147,"name":"gram","plural":"grams"},
                    "units":[226,180,147,389]
                }
            ],
            "id":12430,
            "description":"",
            "name":"Weekend Breakfast"
        }

Create Meal

The Create Meal endpoint creates a meal with the given food contained in the post body.

Resource URL

POST https://api.fitbit.com/1/user/[user-id]/meals.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-LanguageoptionalUsed to determine the food measurement units returned.

POST Parameters

namerequiredName of the meal.
DescriptionrequiredShort description of the meal.
foodIdrequiredID of the food to be included in the meal.
unitIdrequiredID of units used. Typically retrieved via a previous call to Get Food Logs, Search Foods, or Get Food Units.
amountrequiredAmount consumed; in the format X.XX, in the specified unitId.

POST Body Format

{
    "name" : <value>,
    "description" : <value>,
    "mealFoods" : [ 
        {
            "foodId" : <value>,
            "amount" : <value>,
            "unitId" : <value>

        },
        <...>
    ] 

}
Example POST Body
{
    "name" : "Sunday Brunch",
    "description" : "Typical sunday brunch",
    "mealFoods" : [ 
        {
            "foodId" : 80851,
            "amount" : 2,
            "unitId" : 111

        },
        {
            "foodId" : 81170,
            "amount" : 10,
            "unitId" : 311

        },
        {
            "foodId" : 82782,
            "amount" : 8,
            "unitId" : 128

        },
        {
            "foodId" : 9942,
            "amount" : 1,
            "unitId" : 180

        }
    ] 

}

Response Format

For example meal see Example Meal

{ "meal" : <meal> }

Get Meal

The Get Meal endpoint retrieves a meal for a user given the meal id.

Resource URL

GET https://api.fitbit.com/1/user/[user-id]/meals/[meal-id].json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
meal-idThe ID of the meal.

Request Headers

Accept-LanguageoptionalUsed to determine the food measurement units returned.

Example Response

For example meal see Example Meal

{
    "meal": <meal>
}

Edit Meal

The Edit Meal endpoint replaces an existing meal with the contents of the request. The response contains the updated meal.

Resource URL

POST https://api.fitbit.com/1/user/[user-id]/meals/[meal-id].json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
meal-idThe ID of the meal to update.

Request Headers

Accept-LanguageoptionalUsed to determine the food measurement units returned.

POST Parameters

namerequiredName of the meal.
DescriptionrequiredShort description of the meal.
foodIdrequiredID of the food to be included in the meal.
unitIdrequiredID of units used. Typically retrieved via a previous call to Get Food Logs, Search Foods, or Get Food Units.
amountrequiredAmount consumed; in the format X.XX, in the specified unitId.

POST Body Format

{
    "name" : <value>,
    "description" : <value>,
    "mealFoods" : [ 
        {
            "foodId" : <value>,
            "amount" : <value>,
            "unitId" : <value>

        },
        <...>
    ] 

}

Response Format

For example meal see Example Meal

{ "meal" : <meal> }

Delete Meal

Deletes a user's meal with the given meal id.

Resource URL

DELETE https://api.fitbit.com/1/user/[user-id]/meals/[meal-id].json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
meal-idThe ID of the meal.

A successful request returns a 204 status code and an empty response body.

Create Food

The Create Food endpoint creates a new private food for a user and returns a response in the format requested. The created food is found via the Search Foods call.

Note: Foods created via this endpoint will have a PRIVATE value in the accessLevel field when accesson behalf of the authorized user and SHARED when viewed by any other user (if authorized user granted respective Foods permission.)

Resource URL

POST https://api.fitbit.com/1/user/[user-id]/foods.json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-LanguageoptionalUsed to determine the food measurement units returned.

POST Parameters

namerequiredFood name.
defaultFoodMeasurementUnitIdrequiredID of the default measurement unit. Full list of units can be retrieved via the Get Food Units endpoint.
defaultServingSizerequiredSize of the default serving. Nutritional values should be provided for this serving size.
caloriesrequiredCalories in the default serving size.
formTypeoptionalForm type (LIQUID or DRY.)
descriptionoptionalDescription of the food.

More Nutrition Information

CommonVitaminsDietary Minerals
caloriesFromFat
totalFat(g)
transFat(g)
saturatedFat(g)
cholesterol(mg)
sodium(mg)
potassium(mg)
totalCarbohydrate(g)
dietaryFiber(g)
sugars(g)
protein(g)
vitaminA(IU)
vitaminB6
vitaminB12
vitaminC(mg)
vitaminD(IU)
vitaminE(IU)
biotin(mg)
folicAcid(mg)
niacin(mg)
pantothenicAcid(mg)
riboflavin(mg)
thiamin(mg)
calcium(g)
copper(g)
iron(mg)
magnesium(mg)
phosphorus(g)
iodine(mcg)
zinc(mg)

Additional Nutrition Information (optional)

To track nutritional information not listed here, put the key and value into the additional nutirition section.

Example Response

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

{
    "food":
        {
            "accessLevel":"PRIVATE",
            "brand":"",
            "calories":100,
            "defaultServingSize":1,
            "defaultUnit":{
                "id":100,
                "name":"dolma",
                "plural":"dolmas"
            },
            "foodId":490768,
            "name":"TestFood",
            "units":[541]
        }
}

Delete Custom Food

The Delete Custom Food endpoint deletes custom food for a user and returns a response in the format requested.

Resource URL

DELETE https://api.fitbit.com/1/user/[user-id]/foods/[food-id].json

user-idThe ID of the user. Use "-" (dash) for current logged-in user.
food-idThe ID of the food to be deleted.

Successful calls return a 204 response code with an empty body.

General Resources

Get Food

The Get Food endpoint returns the details of a specific food in the Fitbit food database or a private food the authorized user has entered in the format requested.

Considerations

Nutritional values are currently included in responses, but only for PRIVATE or SHARED foods.

Resource URL

GET https://api.fitbit.com/1/foods/[food-id].json

food-idThe ID of the food.

Request Headers

Accept-LanguageoptionalUsed to determine the food measurement units returned.

Example Response

{
    "food":
        {
            "accessLevel":"PUBLIC",
            "brand":"Philadelphia Brand",
            "calories":60,
            "defaultServingSize":2,
            "defaultUnit":{"id":349,"name":"tbsp","plural":"tbsp"},
            "foodId":12323,
            "locale":"en_US",
            "name":"Cream Cheese, Ranch, Whipped",
            "servings":[
                {
                    "multiplier":1,
                    "servingSize":2,
                    "unitId":349
                    "unit":{"id":349,"name":"tbsp","plural":"tbsp"},
                },
                {
                    "multiplier":1,
                    "servingSize":0.7400000095367432,
                    "unitId":226
                }
            ],
            "units":[349,364,226,180,147,389],
            "nutritionalValues":
                {
                    "biotin":0,
                    "calcium":0,
                    "calories":60,
                    "caloriesFromFat":52,
                    "cholesterol":15,
                    "copper":0,
                    "dietaryFiber":0,
                    "folicAcid":0,
                    "iodine":0,
                    "iron":0,
                    "magnesium":0,
                    "niacin":0,
                    "pantothenicAcid":0,
                    "phosphorus":0,
                    "potassium":0,
                    "protein":1,
                    "riboflavin":0,
                    "saturatedFat":3.5,
                    "sodium":150,
                    "sugars":1,
                    "thiamin":0,
                    "totalCarbohydrate":1,
                    "totalFat":6,
                    "transFat":0,
                    "vitaminA":300,
                    "vitaminB12":0,
                    "vitaminB6":0,
                    "vitaminC":0,
                    "vitaminD":0,
                    "vitaminE":0,
                    "zinc":0
                }
        }
}

Get Food Units

The Get Food Units endpoint returns a list of all valid Fitbit food units in the format requested.

Typically, an application retrieves the complete list of units once at startup. From then on, the application will receive a food-specific list of unit ids along with the Favorite, Recent, or Frequent food or by making a query to Search Foods endpoint. These are the IDs of units that apply to the favorite food. The application will refer to the complete list of units retrieved previously to get and display to the user the unit name or plural name for each unit ID on food-specific list.

Resource URL

GET https://api.fitbit.com/1/foods/units.json

Request Headers

Accept-LocaleoptionalThe locale to use for response values. Locale is used to determine locale of the food units in the response.

Search Foods

Given a search query, the Search Foods endpoint returns a list of public foods from Fitbit foods database and private foods the user created in the format requested.

Considerations

  1. The units field contains references to respective Food Units.
  2. The accessLevel field can be either PUBLIC, PRIVATE, or SHARED.

Resource URL

GET https://api.fitbit.com/1/foods/search.json

POST Parameters

queryrequiredThe URL-encoded search query

Example Response

{
    "foods": [
        {
            "accessLevel":"PUBLIC",
            "calories":570,
            "defaultServingSize":100,
            "defaultUnit":{"id":147,"name":"gram","plural":"grams"},
            "foodId":18828,
            "locale":"en_US",
            "name":"Chocolate, Milk",
            "units":[226,180,147,389]
        },
        {
            "accessLevel":"PRIVATE",
            "calories":564,
            "defaultServingSize":100,
            "defaultUnit":{"id":147,"name":"gram","plural":"grams"},
            "foodId":14823,
            "name":"Chocolate, Bitter",
            "units":[226,180,147,389]
        },
        {
            "accessLevel":"PUBLIC",
            "brand":"Bounty",
            "calories":488,
            "defaultServingSize":100,
            "defaultUnit":{"id":147,"name":"gram","plural":"grams"},
            "foodId":23500,
            "locale":"en_US",
            "name":"Chocolate, Bounty",
            "units":[226,180,147,389]
        }
    ]
}