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.

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
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").
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" ?>
<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>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
13 Invalid token: "<detail>"
107 Value out of range: "<detail>"
FatSecret Sites
For Developers

For Professionals

For Everyone

FatSecret Platform API

Developers

Support
API

About FatSecret

© 2022 FatSecret. All rights reserved.