fatsecret Platform API Documentation

Foods: Search

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.

An interactive demonstration of our Food Search API can be accessed here

Parameters

URL / Method

NAME	TYPE	REQUIRED	DESCRIPTION
URL (new) Method	N/A	Required	"https://platform.fatsecret.com/rest/foods/search/v1" HTTP "GET"
OR
method	String	Required	"foods.search" (included with other parameters)

Additional Parameters

NAME	TYPE	REQUIRED	DESCRIPTION
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. If not specified this will default to "US" (United States). Click here for full documentation on localization.
language	String	Optional	(Ignored unless region is also specified) Results will be in the specified language. E.G.: "fr" returns results in French

Scopes for OAuth2 integration: premier

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

Example Response

⚠️ Response json is only in array format when more than one object is returned

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://foods.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://foods.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>