Food Logging

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-id The 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-id The ID of the user. Use "-" (dash) for current logged-in user.
date The 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-Language optional Used 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-id The ID of the user. Use "-" (dash) for current logged-in user.
date The 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-Language optional Used 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-id The 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:

GET https://api.fitbit.com/1/user/[user-id]/[resource-path]/date/[date]/[period].json
api-version The API version. Currently version 1.
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.
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


GET https://api.fitbit.com/1/user/[user-id]/[resource-path]/date/[base-date]/[end-date].json
api-version The API version. Currently version 1.
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 formatyyyy-MM-dd or today.
end-date The 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-Language optional The 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-id The ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

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

POST Parameters

foodId optional/required ID of the food to be logged. Either foodId or foodName must be provided.
foodName optional/required Food entry name. Either foodId or foodName must be provided.
mealTypeId required Meal type. 1=Breakfast; 2=Morning Snack; 3=Lunch; 4=Afternoon Snack; 5=Dinner; 7=Anytime.
unitId required ID of units used. Typically retrieved via a previous call to Get Food Logs, Search Foods, or Get Food Units.
amount required Amount consumed; in the format X.XX, in the specified unitId.
date required Log entry date; in the format yyyy-MM-dd.
favorite optional true will add the food to the user's favorites after creating the log entry; false will not. Valid only with foodId.
brandName optional Brand name of food. Valid only with foodName parameter.
calories optional Calories for this serving size. Allowed with foodName parameter (defaults to zero); otherwise ignored.

Additional Nutrition Information (optional and valid only with foodName)

Common Vitamins Dietary 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-id The ID of the user. Use "-" (dash) for current logged-in user.
food-log-id The ID of the food log to edit

Request Headers

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

POST Parameters

mealTypeId required Meal type. 1=Breakfast; 2=Morning Snack; 3=Lunch; 4=Afternoon Snack; 5=Dinner; 7=Anytime.
unitId optional/required ID 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.
amount optional/required Amount consumed; Not required if the food log was created with the foodName parameter. In the format X.XX, in the specified unitId.
calories optional/required Calories 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-id The ID of the user. Use "-" (dash) for current logged-in user.
date The date of records to be returned. In the format yyyy-MM-dd.

Request Headers

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

POST Parameters

amount required Amount consumed; in the format X.X and in the specified waterUnit or in the unit system that corresponds to the Accept-Language header provided.
date required Log entry date; in the format yyyy-MM-dd.
unit optional Water 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-id The ID of the user. Use "-" for current logged-in user.

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.

Example Request

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

POST Parameters

calories optional/required Manual calorie consumption goal in integer format. Either calories or intensity must be provided.
intensity optional/required Food plan intensity (MAINTENANCE, EASIER, MEDIUM, KINDAHARD, or HARDER). Either calories or intensity must be provided.
personalized optional Food 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-id The ID of the user. Use "-" (dash) for current logged-in user.

POST Parameters

target required Target 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-id The ID of the user. Use "-" (dash) for current logged-in user.
food-log-id The 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-Language optional The measurement unit system to use for POST parameters and response values.

POST Parameters

amount required Amount consumed; in the format X.X and in the specified waterUnit or in the unit system that corresponds to the Accept-Language header provided.
unit optional Water 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-id The ID of the user. Use "-" (dash) for current logged-in user.
water-log-id The 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-id The ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-Language optional Used 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-id The ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-Language optional Used 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-id The ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-Language optional Used 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-id The ID of the user. Use "-" (dash) for current logged-in user.
food-id The 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-id The ID of the user. Use "-" (dash) for current logged-in user.
food-id The 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-id The ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-Language optional Used 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-id The ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-Language optional Used to determine the food measurement units returned.

POST Parameters

name required Name of the meal.
Description required Short description of the meal.
foodId required ID of the food to be included in the meal.
unitId required ID of units used. Typically retrieved via a previous call to Get Food Logs, Search Foods, or Get Food Units.
amount required Amount 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-id The ID of the user. Use "-" (dash) for current logged-in user.
meal-id The ID of the meal.

Request Headers

Accept-Language optional Used 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-id The ID of the user. Use "-" (dash) for current logged-in user.
meal-id The ID of the meal to update.

Request Headers

Accept-Language optional Used to determine the food measurement units returned.

POST Parameters

name required Name of the meal.
Description required Short description of the meal.
foodId required ID of the food to be included in the meal.
unitId required ID of units used. Typically retrieved via a previous call to Get Food Logs, Search Foods, or Get Food Units.
amount required Amount 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-id The ID of the user. Use "-" (dash) for current logged-in user.
meal-id The 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 access on 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-id The ID of the user. Use "-" (dash) for current logged-in user.

Request Headers

Accept-Language optional Used to determine the food measurement units returned.

POST Parameters

name required Food name.
defaultFoodMeasurementUnitId required ID of the default measurement unit. Full list of units can be retrieved via the Get Food Units endpoint.
defaultServingSize required Size of the default serving. Nutritional values should be provided for this serving size.
calories required Calories in the default serving size.
formType optional Form type (LIQUID or DRY.)
description optional Description of the food.

More Nutrition Information

Common Vitamins Dietary 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 nutrition 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-id The ID of the user. Use "-" (dash) for current logged-in user.
food-id The 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-id The ID of the food.

Request Headers

Accept-Language optional Used 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-Locale optional The 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

query required The 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]
        }
    ]
}