FatSecret Platform API Documentation

Foods: Search

OAuth 2.0 OAuth 1.0
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.

Search results will be refined according to the user's prior saved food entries.

Parameters
All
NAME TYPE REQUIRED DESCRIPTION
method String Required MUST be "foods.search"
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
format String Optional The desired response format. Valid response formats are "xml" or "json" (default value is "xml").
Premier Exclusive
Name Type Required Description
generic_description String Optional 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
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
The only storable value returned by this call is food_id.

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

Example Response

Example 1:

<?xml version="1.0" encoding="utf-8"?>
<foods 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>
  <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>
    <food_description>Per 1 serving - Calories: 300kcal | Fat: 13.00g | Carbs: 32.00g | Protein: 15.00g
    </food_description>
  </food>
</foods>

Example 2:

<?xml version="1.0" encoding="utf-8"?>
<foods 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>
  <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>
    <food_description>Per 100g - Calories: 22kcal | Fat: 0.34g | Carbs: 3.28g | Protein: 3.09g</food_description>
  </food>
</foods>

Example 1:

{
  "foods": {
    "food": {
      "brand_name": "McDonald's",
      "food_description": "Per 1 serving - Calories: 300kcal | Fat: 13.00g | Carbs: 32.00g | Protein: 15.00g",
      "food_id": "41963",
      "food_name": "Cheeseburger",
      "food_type": "Brand",
      "food_url": "https://www.fatsecret.com/calories-nutrition/mcdonalds/cheeseburger"
    },
    "max_results": "1",
    "page_number": "0",
    "total_results": "220"
  }
}

Example 2:

{
  "foods": {
    "food": {
      "food_description": "Per 100g - Calories: 22kcal | Fat: 0.34g | Carbs: 3.28g | Protein: 3.09g",
      "food_id": "36421",
      "food_name": "Mushrooms",
      "food_type": "Generic",
      "food_url": "https://www.fatsecret.com/calories-nutrition/usda/mushrooms"
    },
    "max_results": "1",
    "page_number": "0",
    "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>'