FatSecret Platform API Documentation
Description
Conducts a search of the food database using the search expression specified. The results are paginated according to a zero-based "page" offset. Successive pages of results may be retrieved by specifying a starting page offset value. For instance, specifying a max_results of 10 and page_number of 4 will return results numbered 41-50.
Returns detailed nutritional information for the specified food. Use this call to display nutrition values for a food to users.
An interactive demonstration of our Food Search API can be accessed here
Why are we introducing version 2?
We are introducing version 2 to allow the content from the food.get.v3 api to respond directly from a food search. This will negate requirements to issue any subsequent calls to the food.get.v3 api.
Updated json array formatting so it is consistent when one object is returned.
Parameters
All
| NAME | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| method | String | Required | MUST be "foods.search.v2" |
| search_expression | String | Optional | Search expression to match on food names |
| page_number | Int | Optional | Zero-based offset into the results for the query |
| max_results | Int | Optional | Maximum number of results to return (default value is 20). This number cannot be greater than 50 |
| 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 |
| format | String | Optional | The desired response format. Valid response formats are "xml" or "json" (default value is "xml"). |
Response
Each foods_search element contains information as follows:
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| max_results | Int | Maximum number of results to return (default value is 20). This number cannot be greater than 50 |
| total_results | Int | Total number of search results matching the search expression |
| page_number | Int | Zero-based offset into the results for the query |
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" |
| brand_name | String | Brand name, only when food_type is "Brand". E.G.: "Quaker" |
| 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 |
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 |
| 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) |
| trans_fat | Decimal | Trans 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) |
| added_sugars | Decimal | Added Sugars content in grams (where available) |
| calcium | Decimal | Calcium content in milligrams (where available) |
| iron | Decimal | Iron content in milligrams (where available) |
| 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) |
| polyunsaturated_fat | Decimal | Polyunsaturated fat content in grams (where available) |
| monounsaturated_fat | Decimal | Monounsaturated fat 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) |
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
Example 1:
<?xml version="1.0" encoding="utf-8"?>
<foods_search xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://platform.fatsecret.com/api/1.0/"
xsi:schemaLocation="http://platform.fatsecret.com/api/1.0/ http://platform.fatsecret.com/api/1.0/fatsecret.xsd">
<max_results>1</max_results>
<total_results>220</total_results>
<page_number>0</page_number>
<results>
<food>
<food_id>41963</food_id>
<food_name>Cheeseburger</food_name>
<brand_name>McDonald's</brand_name>
<food_type>Brand</food_type>
<food_url>https://www.fatsecret.com/calories-nutrition/mcdonalds/cheeseburger</food_url>
<servings>
<serving>
<serving_id>87220</serving_id>
<serving_description>1 serving</serving_description>
<serving_url>https://www.fatsecret.com/calories-nutrition/mcdonalds/cheeseburger</serving_url>
<number_of_units>1.000</number_of_units>
<measurement_description>serving</measurement_description>
<is_default>1</is_default>
<calories>300</calories>
<carbohydrate>32.00</carbohydrate>
<protein>15.00</protein>
<fat>13.00</fat>
<saturated_fat>6.000</saturated_fat>
<trans_fat>0.500</trans_fat>
<cholesterol>40</cholesterol>
<sodium>720</sodium>
<potassium>220</potassium>
<fiber>2.0</fiber>
<sugar>7.00</sugar>
<added_sugars>5.00</added_sugars>
<calcium>100</calcium>
<iron>3.00</iron>
</serving>
</servings>
<food_sub_categories>
<food_sub_category>Cheeseburgers</food_sub_category>
<food_sub_category>Burgers</food_sub_category>
</food_sub_categories>
</food>
</results>
</foods_search>Example 2:
<?xml version="1.0" encoding="utf-8"?>
<foods_search 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">
<max_results>1</max_results>
<total_results>1129</total_results>
<page_number>0</page_number>
<results>
<food>
<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>16758</serving_id>
<serving_description>regular slice</serving_description>
<serving_url>http://www.fatsecret.com/calories-nutrition/generic/french-toast-plain?portionid=16758&portionamount=1.000</serving_url>
<metric_serving_amount>65.000</metric_serving_amount>
<metric_serving_unit>g</metric_serving_unit>
<number_of_units>1.000</number_of_units>
<measurement_description>regular slice</measurement_description>
<calories>159</calories>
<carbohydrate>20.02</carbohydrate>
<protein>5.58</protein>
<fat>6.13</fat>
<saturated_fat>1.585</saturated_fat>
<polyunsaturated_fat>1.578</polyunsaturated_fat>
<monounsaturated_fat>2.298</monounsaturated_fat>
<trans_fat>0</trans_fat>
<cholesterol>90</cholesterol>
<sodium>320</sodium>
<potassium>80</potassium>
<fiber>0.8</fiber>
<sugar>4.87</sugar>
<added_sugars>10</added_sugars>
<vitamin_d>2</vitamin_d>
<vitamin_a>0</vitamin_a>
<vitamin_c>0</vitamin_c>
<calcium>8</calcium>
<iron>9</iron>
</serving>
</servings>
<food_sub_categories>
<food_sub_category>Mushrooms</food_sub_category>
<food_sub_category>Vegetables</food_sub_category>
</food_sub_categories>
</food>
</results>
</foods_search>Example 1:
{
"foods_search": {
"max_results": "1",
"page_number": "0",
"results": {
"food": [
{
"brand_name": "McDonald's",
"food_id": "41963",
"food_name": "Cheeseburger",
"food_sub_categories": {
"food_sub_category": [
"Cheeseburgers",
"Burgers"
]
},
"food_type": "Brand",
"food_url": "https://www.fatsecret.com/calories-nutrition/mcdonalds/cheeseburger",
"servings": {
"serving": [
{
"added_sugars": "5.00",
"calcium": "100",
"calories": "300",
"carbohydrate": "32.00",
"cholesterol": "40",
"fat": "13.00",
"fiber": "2.0",
"iron": "3.00",
"is_default": "1",
"measurement_description": "serving",
"number_of_units": "1.000",
"potassium": "220",
"protein": "15.00",
"saturated_fat": "6.000",
"serving_description": "1 serving",
"serving_id": "87220",
"serving_url": "https://www.fatsecret.com/calories-nutrition/mcdonalds/cheeseburger",
"sodium": "720",
"sugar": "7.00",
"trans_fat": "0.500"
}
]
}
}
]
},
"total_results": "220"
}
}Example 2:
{
"foods_search": {
"max_results": "1",
"page_number": "0",
"results": {
"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": [
{
"added_sugars": "10",
"calcium": "8",
"calories": "159",
"carbohydrate": "20.02",
"cholesterol": "90",
"fat": "6.13",
"fiber": "0.8",
"iron": "9",
"measurement_description": "regular slice",
"metric_serving_amount": "65.000",
"metric_serving_unit": "g",
"monounsaturated_fat": "2.298",
"number_of_units": "1.000",
"polyunsaturated_fat": "1.578",
"potassium": "80",
"protein": "5.58",
"saturated_fat": "1.585",
"serving_description": "regular slice",
"serving_id": "16758",
"serving_url": "http://www.fatsecret.com/calories-nutrition/generic/french-toast-plain?portionid=16758&portionamount=1.000",
"sodium": "320",
"sugar": "4.87",
"trans_fat": "0",
"vitamin_a": "0",
"vitamin_c": "0",
"vitamin_d": "2"
}
]
}
}
]
},
"total_results": "1129"
}
}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>' |