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: Search v1

Foods: Search v1

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.

Passing an oauth_token (i.e.: a logged in user token) is optional. Where the oauth_token is specified, search results will be refined according to the user's prior saved food entries.

The only storable values returned by this call are the food_id unique food identifiers of each food matching the search expression.

Changing Search Result Description Formatting (Premier Only):

An additional optional parameter named generic_description is available to premier clients only. This parameter, of type String, may have a value of either "weight" or "portion":

weight (default) - the summary description for key nutritional values is displayed by weight (typically 100g); E.G.: "Per 100g"
portion - the summary description for key nutritional values is displayed using the default portion size; E.G.: "Per 1 Cup"

Note that the summary nutrition description for "Brand" food items is always shown using a "portion" based description.

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 "foods.search"

Optional

Name	Type	Description
format	String	The desired response format. Valid reponse formats are "xml" or "json" (default value is "xml").
oauth_token	String	The key of the profile to use.
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.

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 contains summary information about the food item as follows:

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.
food_description – A summary description of key nutritional values for a nominated serving size.

Example Return XML

<?xml version="1.0" encoding="utf-8" ?>

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

<food_description>Per 342g - Calories: 835kcal | Fat: 32.28g | Carbs: 105.43g | Protein: 29.41g</food_description>

</food>

</foods>

Example Return JSON

{ "foods": {"food": {"food_description": "Per 342g - Calories: 835kcal | Fat: 32.28g | Carbs: 105.43g | Protein: 29.41g", "food_id": "4384", "food_name": "Plain French Toast", "food_type": "Generic", "food_url": "http:\/\/www.fatsecret.com\/calories-nutrition\/generic\/french-toast-plain" }, "max_results": "20", "page_number": "0", "total_results": "228" }}

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>"
9	Invalid access token: "<detail>"
107	Value out of range: "<detail>"