Guides

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

API Reference (OAuth 2.0)

Overview
Foods
- Find id for barcode*
- Get by id v3
- Get by id v2 (deprecated)
- Get by id v1 (deprecated)
- Autocomplete search expression v2*
- Autocomplete search expression* (deprecated)
- Search v2*
- Search v1
Food Brands
- Get all v2*
- Get all* (deprecated)
Food Categories
- Get all v2*
- Get all* (deprecated)
Food Sub Categories
- Get all v2*
- Get all* (deprecated)
Recipes
- Get by id v2
- Get by id v1 (deprecated)
- Search v3
- Search v2 (deprecated)
- Search v1 (deprecated)
Recipe Types
- Get all v2
- Get all v1 (deprecated)

API Reference (OAuth 1.0)

Overview

Foods
- Find id for barcode*
- Get by id v3
- Get by id v2 (deprecated)
- Get by id v1 (deprecated)
- Autocomplete search expression v2*
- Autocomplete search expression* (deprecated)
- Search v2*
- Search v1
Food Brands
- Get all v2*
- Get all* (deprecated)
Food Categories
- Get all v2*
- Get all* (deprecated)
Food Sub Categories
- Get all v2*
- Get all* (deprecated)
Recipes
- Get by id v2
- Get by id v1 (deprecated)
- Search v3
- Search v2 (deprecated)
- Search v1 (deprecated)
Recipe Types
- Get all v2
- Get all v1 (deprecated)
Exercises
- Get all v2
- Get all (deprecated)
Profile - Foods
- Create v2*
- Create v1* (deprecated)
- Add favorite
- Delete favorite
- Get favorites v2
- Get favorites (deprecated)
- Get most eaten v2
- Get most eaten (deprecated)
- Get recently eaten v2
- Get recently eaten (deprecated)
Profile - Recipes
- Add favorite
- Delete favorite
- Get favorites v2
- Get favorites (deprecated)
Profile - Saved Meals
- Create meal
- Delete meal by id
- Edit meal by id
- Get all meals v2
- Get all meals (deprecated)
- Add food to meal
- Delete food from meal
- Edit food in meal
- Get all foods in meal v2
- Get all foods in meal (deprecated)
Profile - Authentication
- Create profile
- Get profile status
- Get profile auth
Profile - Food Diary
- Copy entries between dates
- Copy entries between meals
- Get all entries v2
- Get all entries (deprecated)
- Get all entries for month v2
- Get all entries for month (deprecated)
- Create entry by id
- Delete entry by id
- Edit entry by id
Profile - Exercise Diary
- Commit day
- Get all for date v2
- Get all for date (deprecated)
- Get calories expended for month v2
- Get calories expended for month (deprecated)
- Save template
- Edit entries for date
Profile - Weight Diary
- Update for date
- Get for month v2
- Get for month (deprecated)

* denotes methods only available at the PREMIER level

Developers

REST API

API Reference (OAuth 1): Foods: Get by id v3

Foods: Get by id v3

Description

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 this version?

This version contains an update to the JSON output structure.

Including Sub Categories (Premier Only):

An additional optional parameter named include_sub_categories is available to premier clients only. 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 (Premier Only):

An additional optional parameter named flag_default_serving is available to premier clients only. 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 (Premier Only):

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

Parameters

Required

Name	Type	Description
oauth_consumer_key	String	Your API key when you registered as a developer
oauth_signature_method	String	The method used to generate the signature (only HMAC-SHA1 is supported)
oauth_timestamp	Int	The date and time, expressed in the number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value must be a positive integer and must be equal or greater than the timestamp used in previous requests
oauth_nonce	String	A randomly generated string for a request that can be combined with the timestamp to produce a unique value
oauth_version	String	MUST be "1.0"
oauth_signature	String	The signature, a consistent reproducible concatenation of the request elements into a single string. The string is used as an input in hashing or signing algorithms.
method	String	MUST be "food.get.v3"
food_id	Long	The ID of the food to retrieve.

Optional

Name	Type	Description
format	String	The desired response format. Valid reponse formats are "xml" or "json" (default value is "xml").

Response

The 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" ?>

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

<added_sugars>10</added_sugars>

<vitamin_d>2</vitamin_d>

<vitamin_a>0</vitamin_a>

<vitamin_c>0</vitamin_c>

</serving>

</servings>

</food>

Example Return JSON

{ "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": [ {"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" } ] } }}

Error Code

Code	Description
2	Missing required oauth parameter: "<detail>"
3	Unsupported oauth parameter: "<detail>"
4	Invalid signature method: "<detail>"
5	Invalid consumer key: "<detail>"
6	Invalid/expired timestamp: "<detail>"
7	Invalid/used nonce: "<detail>"
8	Invalid signature: "<detail>"
101	Missing required parameter: "<detail>"
106	Invalid ID: "<detail>"