Guides

Welcome
Authentication
OAuth 2.0
OAuth 1.0
3-Legged OAuth
Data Types
Storable Data
Error Codes
Localization*

Method Overview
Foods
food.find_id_for_barcode*
food.get.v2
food.get (deprecated)
foods.autocomplete*
foods.search.v2*
foods.search
Food Brands
food_brands.get*
Food Categories
food_categories.get*
Food Sub Categories
food_sub_categories.get*
Recipes
recipe.get.v2
recipe.get
recipes.search.v3
recipes.search.v2
recipes.search
Recipe Types
recipe_types.get.v2
recipe_types.get

API Method Reference (OAuth 1.0)

Method Overview
Foods
food.add_favorite
food.create.v2*
food.create* (deprecated)
food.delete_favorite
food.find_id_for_barcode*
food.get.v2
food.get (deprecated)
foods.autocomplete*
foods.get_favorites
foods.get_most_eaten
foods.get_recently_eaten
foods.search.v2*
foods.search
Food Brands
food_brands.get*
Food Categories
food_categories.get*
Food Sub Categories
food_sub_categories.get*
Recipes
recipe.add_favorite
recipe.delete_favorite
recipe.get.v2
recipe.get
recipes.get_favorites
recipes.search.v3
recipes.search.v2
recipes.search
Recipe Types
recipe_types.get.v2
recipe_types.get
Saved Meals
saved_meal.create
saved_meal.delete
saved_meal.edit
saved_meals.get
saved_meal_item.add
saved_meal_item.delete
saved_meal_item.edit
saved_meal_items.get
Exercises
exercises.get
Profile - Management
profile.create
profile.get
profile.get_auth
Profile - Food Diary
food_entries.copy
food_entries.copy_saved_meal
food_entries.get
food_entries.get_month
food_entry.create
food_entry.delete
food_entry.edit
Profile - Exercise Diary
exercise_entries.commit_day
exercise_entries.get
exercise_entries.get_month
exercise_entries.save_template
exercise_entry.edit
Profile - Weight Diary
weight.update
weights.get_month

* denotes methods only available at the PREMIER level

Developers

REST API

API Method Reference (OAuth 2): foods.search.v2

foods.search.v2

Description

Premier Only
Please note: This API call is available for Premier clients only

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.

The only storable values returned by this call are the food_id unique identifier and the one or more serving_id unique serving size identifier values.

Why are we introducing version 2?

We are introducing version 2 to allow the content from the food.get.v2 api to respond directly from a food search. This will negate requirements to issue any subsequent calls to the food.get.v2 api.

Including Sub Categories:

An additional optional parameter named include_sub_categories is available. This parameter, of type Boolean should be specified as “true” in order to enable this feature.
When this parameter is included, the response will include the names of all sub categories associated with the food.

Flag Default Serving:

An additional optional parameter named flag_default_serving is available. This parameter, of type Boolean should be specified as “true” in order to enable this feature.
When this parameter is included, the response will flag one of the servings as the default serving (the suggested or most commonly chosen option).

Localization:

Two additional optional parameters named region and language are available. More information can be found in the Localization guide.

Parameters

Required

Name	Type	Description
method	String	MUST be "foods.search.v2"

Optional

Name	Type	Description
format	String	The desired response format. Valid reponse formats are "xml" or "json" (default value is "xml").
search_expression	String	The search expression to match on food names.
page_number	Int	The zero-based offset into the results for the query. Use this parameter with max_results to request successive pages of search results (default value is 0).
max_results	Int	The maximum number of results to return (default value is 20). This number cannot be greater than 50.
include_sub_categories	Bool	When this parameter is passed as true, the response will include the names of all sub categories associated with the food.
flag_default_serving	Bool	When this parameter is passed as true, the response will flag one of the servings as the default serving (the suggested or most commonly chosen option).

Response

The food elements returned are those best matching the search expression specified, ordered by their relevancy to the search expression.

The general information returned is:

max_results is an Int – the maximum size of a page of results.
total_results is an Int – the total number of search results matching the search expression.
page_number is an Int – the zero-based offset into the results for the query.

Each food element returned contains general information about the food item with detailed nutritional information for each available standard serving size

The general information returned is:

food_id – the unique food identifier.
food_name – the name of the food, not including the brand name. E.G.: "Instant Oatmeal".
food_type – takes the value "Brand" or "Generic". Indicates whether the food is a brand or generic item – see food_type.
brand_name – the brand name, only when food_type is "Brand". E.G.: "Quaker".
food_url – URL of this food item on www.fatsecret.com.

Nutrient values for each food item are returned according to the standard serving sizes available. The elements returned for each standard serving size are:

serving_id – the unique serving identifier.
serving_description – the full description of the serving size. E.G.: "1 cup" or "100 g".
serving_url – URL of the serving size for this food item on www.fatsecret.com.
metric_serving_amount is a Decimal - the metric quantity combined with metric_serving_unit to derive the total standardized quantity of the serving (where available).
metric_serving_unit – the 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 is a Decimal - the 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 – 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".

The complete nutritional information is returned - see nutrient

calories is a Decimal – the energy content in kcal.
carbohydrate is a Decimal – the total carbohydrate content in grams.
protein is a Decimal – the protein content in grams.
fat is a Decimal – the total fat content in grams.
saturated_fat is a Decimal – the saturated fat content in grams (where available).
polyunsaturated_fat is a Decimal – the polyunsaturated fat content in grams (where available).
monounsaturated_fat is a Decimal – the monounsaturated fat content in grams (where available).
trans_fat is a Decimal – the trans fat content in grams (where available).
cholesterol is a Decimal – the cholesterol content in milligrams (where available).
sodium is a Decimal – the sodium content in milligrams (where available).
potassium is a Decimal – the potassium content in milligrams (where available).
fiber is a Decimal – the fiber content in grams (where available).
sugar is a Decimal – the sugar content in grams (where available).
added_sugars is a Decimal – the Added Sugars content in grams (where available).
vitamin_d is a Decimal – the Vitamin D content in micrograms (where available).
vitamin_a is a Decimal – the Vitamin A content in micrograms (where available).
vitamin_c is a Decimal – the Vitamin C content in milligrams (where available).
calcium is a Decimal – the Calcium content in milligrams (where available).
iron is a Decimal – the Iron content in milligrams (where available).

Example Return XML

<?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>20</max_results>

<total_results>228</total_results>

<page_number>0</page_number>

<food>

<food_id>4384</food_id>

<food_name>Plain French Toast</food_name>

<food_type>Generic</food_type>

<food_url>http://www.fatsecret.com/calories-nutrition/generic/french-toast-plain</food_url>

<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>

<saturated_fat>1.585</saturated_fat>

<polyunsaturated_fat>1.578</polyunsaturated_fat>

<monounsaturated_fat>2.298</monounsaturated_fat>

<trans_fat>0</trans_fat>

<vitamin_a>0</vitamin_a>

<vitamin_c>0</vitamin_c>

</serving>

</servings>

</food>

</results>

</foods_search>

Example Return JSON

{ "foods_search": {"max_results": "20", "page_number": "0", "results": { "food": [ {"food_id": "4384", "food_name": "Plain French Toast", "food_type": "Generic", "food_url": "http:\/\/www.fatsecret.com\/calories-nutrition\/generic\/french-toast-plain", "servings": { "serving": [ {"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" } ] } } ] }, "total_results": "228" }}