FatSecret Platform API Documentation
Description
Returns detailed nutritional information for the specified food for each available standard serving size. Use this call to display nutrition values for a food to users.
Updates to food labels
On May 27, 2016 the USA Food and Drug Administration (FDA) published new rules on the new Nutrition Facts label for packaged foods to reflect new scientific information, including the link between diet and chronic diseases such as obesity and heart disease.
Manufacturers in the USA with $10 million or more in annual sales were required to switch to the new label by January 1, 2020; manufacturers with less than $10 million in annual food sales have until January 1, 2021 to comply.
More information can be found here: Changes to the Nutrition Facts Label
Please find more information on how to calculate the %DV for your users: Dietary Supplement Label Database
What are the differences between food.get and food.get.v2?
| food.get | food.get.v2 |
|---|---|
|
The Vitamin A value is the percentage of daily recommended.
It is based on a 2000 calorie diet. |
The Vitamin A value is the raw value in micrograms (mcg).
It is up to the developer to calculate the %DV (Percent Daily Value) |
|
The Vitamin C value is the percentage of daily recommended.
It is based on a 2000 calorie diet. |
The Vitamin C value is the raw value in milligrams (mg).
It is up to the developer to calculate the %DV |
|
The Calcium value is the percentage of daily recommended.
It is based on a 2000 calorie diet. |
The Calcium value is the raw value in milligrams (mg).
It is up to the developer to calculate the %DV |
|
The Iron value is the percentage of daily recommended.
It is based on a 2000 calorie diet. |
The Iron value is the raw value in milligrams (mg).
It is up to the developer to calculate the %DV |
| --- | Vitamin D is the raw value in micrograms (mcg). |
| --- |
Added Sugars is the raw value in grams (g).
It is new for our food_type = "Brand" |
Parameters
All
Premier Exclusive
| Name | Type | Required | Description |
|---|---|---|---|
| include_sub_categories | Boolean | Optional | Response will include the names of all sub categories associated with the food |
| flag_default_serving | Boolean | Optional | Either "true" or "false" - the response will flag one of the servings as the default serving (the suggested or most commonly chosen option) |
| region | String | Optional | Results will be filtered by region. E.G.: "FR" returns results from France |
| language | String | Optional | (Ignored unless region is also specified) Results will be in the specified language. E.G.: "fr" returns results in French |
Response
Each food element contains information as follows:
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| food_id | Long | Unique food identifier |
| food_name | String | Name of the food, not including the brand name. E.G.: "Instant Oatmeal" |
| food_type | String | Takes the value "Brand" or "Generic". Indicates whether the food is a brand or generic item |
| food_url | String | URL of this food item on www.fatsecret.com |
| brand_name | String | Brand name, only when food_type is "Brand". E.G.: "Quaker" |
Each serving element contains information as follows:
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| serving_id | Long | Unique serving identifier |
| serving_description | String | Full description of the serving size. E.G.: "1 cup" or "100 g" |
| serving_url | String | URL of the serving size for this food item on www.fatsecret.com |
| metric_serving_amount | Decimal | Metric quantity combined with metric_serving_unit to derive the total standardized quantity of the serving (where available) |
| metric_serving_unit | String | Metric unit of measure for the serving size – either "g" or "ml" or "oz" – combined with metric_serving_amount to derive the total standardized quantity of the serving (where available) |
| number_of_units | Decimal | Number of units in this standard serving size. For instance, if the serving description is "2 tablespoons" the number of units is "2", while if the serving size is "1 cup" the number of units is "1". Please note that this is only applicable for when food_type is "Generic" whereas for "Brand" the number of units will always be "1" |
| measurement_description | String | A description of the unit of measure used in the serving description. For instance, if the description is "1/2 cup" the measurement description is "cup", while if the serving size is "100 g" the measurement description is "g". Please note that this is only applicable for when food_type is "Generic" whereas for "Brand" the measurement description will always be "serving" |
| is_default | Int | (Premier Exclusive) Only included if its the suggested or most commonly chosen option. If included equals 1 |
| calories | Decimal | Energy content in kcal |
| carbohydrate | Decimal | Total carbohydrate content in grams |
| protein | Decimal | Protein content in grams |
| fat | Decimal | Total fat content in grams |
| saturated_fat | Decimal | Saturated fat content in grams (where available) |
| polyunsaturated_fat | Decimal | Polyunsaturated fat content in grams (where available) |
| monounsaturated_fat | Decimal | Monounsaturated fat content in grams (where available) |
| cholesterol | Decimal | Cholesterol content in milligrams (where available) |
| sodium | Decimal | Sodium content in milligrams (where available) |
| potassium | Decimal | Potassium content in milligrams (where available) |
| fiber | Decimal | Fiber content in grams (where available) |
| sugar | Decimal | Sugar content in grams (where available) |
| vitamin_d | Decimal | Vitamin D content in micrograms (where available) |
| vitamin_a | Decimal | Vitamin A content in micrograms (where available) |
| vitamin_c | Decimal | Vitamin C content in milligrams (where available) |
| calcium | Decimal | Calcium content in milligrams (where available) |
| iron | Decimal | Iron content in milligrams (where available) |
| trans_fat | Decimal | Trans fat content in grams (where available) |
| added_sugars | Decimal | Added Sugars content in grams (where available) |
Each food_sub_categories element contains information as follows:
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| food_sub_category | String | (Premier Exclusive) Sub category of the food |
Example Response
⚠️ Response json is only in array format when more than one object is returned
Example 1:
<?xml version="1.0" encoding="utf-8"?>
<food xmlns="http://platform.fatsecret.com/api/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://platform.fatsecret.com/api/1.0/ http://platform.fatsecret.com/api/1.0/fatsecret.xsd">
<food_id>36421</food_id>
<food_name>Mushrooms</food_name>
<food_type>Generic</food_type>
<food_url>https://www.fatsecret.com/calories-nutrition/usda/mushrooms</food_url>
<servings>
<serving>
<serving_id>34244</serving_id>
<serving_description>1 cup pieces or slices</serving_description>
<serving_url>https://www.fatsecret.com/calories-nutrition/usda/mushrooms?portionid=34244&portionamount=1.000</serving_url>
<metric_serving_amount>70.000</metric_serving_amount>
<metric_serving_unit>g</metric_serving_unit>
<number_of_units>1.000</number_of_units>
<measurement_description>cup, pieces or slices</measurement_description>
<is_default>1</is_default>
<calories>15</calories>
<carbohydrate>2.30</carbohydrate>
<protein>2.16</protein>
<fat>0.24</fat>
<saturated_fat>0.035</saturated_fat>
<polyunsaturated_fat>0.112</polyunsaturated_fat>
<monounsaturated_fat>0</monounsaturated_fat>
<cholesterol>0</cholesterol>
<sodium>4</sodium>
<potassium>223</potassium>
<fiber>0.7</fiber>
<sugar>1.16</sugar>
<vitamin_d>1</vitamin_d>
<vitamin_a>0</vitamin_a>
<vitamin_c>1.5</vitamin_c>
<calcium>2</calcium>
<iron>0.35</iron>
</serving>
</servings>
<food_sub_categories>
<food_sub_category>Mushrooms</food_sub_category>
<food_sub_category>Vegetables</food_sub_category>
</food_sub_categories>
</food>Example 2:
<?xml version="1.0" encoding="utf-8"?>
<food xmlns="http://platform.fatsecret.com/api/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://platform.fatsecret.com/api/1.0/ http://platform.fatsecret.com/api/1.0/fatsecret.xsd">
<food_id>433456</food_id>
<food_name>Whole Grain Cheerios 1g of sugar</food_name>
<brand_name>General Mills Cereal</brand_name>
<food_type>Brand</food_type>
<food_url>https://www.fatsecret.com/calories-nutrition/0_1411704_1002131029_Whole+Grain+Cheerios+1g+of+sugar</food_url>
<servings>
<serving>
<serving_id>462681</serving_id>
<serving_description>1 cup</serving_description>
<serving_url>https://www.fatsecret.com/calories-nutrition/0_1411704_1002131029_Whole+Grain+Cheerios+1g+of+sugar</serving_url>
<metric_serving_amount>27.000</metric_serving_amount>
<metric_serving_unit>g</metric_serving_unit>
<number_of_units>1.000</number_of_units>
<measurement_description>serving</measurement_description>
<is_default>1</is_default>
<calories>110</calories>
<carbohydrate>20.00</carbohydrate>
<protein>3.00</protein>
<fat>1.50</fat>
<saturated_fat>0.400</saturated_fat>
<polyunsaturated_fat>0.0</polyunsaturated_fat>
<monounsaturated_fat>0.0</monounsaturated_fat>
<trans_fat>0</trans_fat>
<cholesterol>0</cholesterol>
<sodium>250</sodium>
<potassium>0</potassium>
<fiber>2.0</fiber>
<sugar>1.00</sugar>
<added_sugars>0</added_sugars>
<vitamin_d>0</vitamin_d>
<vitamin_a>0</vitamin_a>
<vitamin_c>0</vitamin_c>
<calcium>0</calcium>
<iron>0</iron>
</serving>
</servings>
</food>Example 1:
{
"food": {
"food_id": "36421",
"food_name": "Mushrooms",
"food_sub_categories": {
"food_sub_category": [
"Mushrooms",
"Vegetables"
]
},
"food_type": "Generic",
"food_url": "https://www.fatsecret.com/calories-nutrition/usda/mushrooms",
"servings": {
"serving": {
"calcium": "2",
"calories": "15",
"carbohydrate": "2.30",
"cholesterol": "0",
"fat": "0.24",
"fiber": "0.7",
"iron": "0.35",
"is_default": "1",
"measurement_description": "cup, pieces or slices",
"metric_serving_amount": "70.000",
"metric_serving_unit": "g",
"monounsaturated_fat": "0",
"number_of_units": "1.000",
"polyunsaturated_fat": "0.112",
"potassium": "223",
"protein": "2.16",
"saturated_fat": "0.035",
"serving_description": "1 cup pieces or slices",
"serving_id": "34244",
"serving_url": "https://www.fatsecret.com/calories-nutrition/usda/mushrooms?portionid=34244&portionamount=1.000",
"sodium": "4",
"sugar": "1.16",
"vitamin_a": "0",
"vitamin_c": "1.5",
"vitamin_d": "1"
}
}
}
}Example 2:
{
"food": {
"brand_name": "General Mills Cereal",
"food_id": "433456",
"food_name": "Whole Grain Cheerios 1g of sugar",
"food_type": "Brand",
"food_url": "https://www.fatsecret.com/calories-nutrition/0_1411704_1002131029_Whole+Grain+Cheerios+1g+of+sugar",
"servings": {
"serving": {
"added_sugars": "0",
"calcium": "0",
"calories": "110",
"carbohydrate": "20.00",
"cholesterol": "0",
"fat": "1.50",
"fiber": "2.0",
"iron": "0",
"is_default": "1",
"measurement_description": "serving",
"metric_serving_amount": "27.000",
"metric_serving_unit": "g",
"monounsaturated_fat": "0.0",
"number_of_units": "1.000",
"polyunsaturated_fat": "0.0",
"potassium": "0",
"protein": "3.00",
"saturated_fat": "0.400",
"serving_description": "1 cup",
"serving_id": "462681",
"serving_url": "https://www.fatsecret.com/calories-nutrition/0_1411704_1002131029_Whole+Grain+Cheerios+1g+of+sugar",
"sodium": "250",
"sugar": "1.00",
"trans_fat": "0",
"vitamin_a": "0",
"vitamin_c": "0",
"vitamin_d": "0"
}
}
}
}Error Codes
| CODE | TYPE | DESCRIPTION |
|---|---|---|
| 2 | OAuth 1.0 | Missing required oauth parameter: '<details>' |
| 3 | OAuth 1.0 | Unsupported oauth parameter: '<details>' |
| 4 | OAuth 1.0 | Invalid signature method: '<details>' |
| 5 | OAuth 1.0 | Invalid consumer key: '<details>' |
| 6 | OAuth 1.0 | Invalid/expired timestamp: '<details>' |
| 7 | OAuth 1.0 | Invalid/used nonce: '<details>' |
| 8 | OAuth 1.0 | Invalid signature: '<details>' |
| 9 | OAuth 1.0 | Invalid access token: '<details>' |
| 13 | OAuth 2.0 | Invalid token: '<details>' |
| 14 | OAuth 2.0 | Missing scope: '<details>' |
| 107 | Parameter | Value out of range: '<details>' |