FatSecret Platform API Documentation

⚠️ This is version has been deprecated. Please upgrade to the latest version.

Recipes: Search

Description

Conducts a search of the recipe 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.

Why are we introducing version 2?

This version will return recipe type and ingredient information. The response will also contain a direct url to the recipe on the fatsecret website. This version also supports advanced filtering updates.

Parameters

All

NAME	TYPE	REQUIRED	DESCRIPTION
method	String	Required	MUST be "recipes.search.v2"
search_expression	String	Optional	Search expression to match on food names
must_have_images	Bool	Optional	This option will restrict results to recipes with at least one image
calories.from	Decimal	Optional	Minimum calories that are contained in the recipe
calories.to	Decimal	Optional	Maximum calories that are contained in the recipe
carb_percentage.from	Long	Optional	Minimum percentage of the calories composed of carbohydrate
carb_percentage.to	Long	Optional	Maximum percentage of the calories composed of carbohydrate
protein_percentage.from	Long	Optional	Minimum percentage of the calories composed of protein
protein_percentage.to	Long	Optional	Maximum percentage of the calories composed of protein
fat_percentage.from	Long	Optional	Minimum percentage of the calories composed of fat
fat_percentage.to	Long	Optional	Maximum percentage of the calories composed of fat
prep_time.from	Long	Optional	Minimum preparation and cook time in minutes required to create the recipe
prep_time.to	Long	Optional	Maximum preparation and cook time in minutes required to create the recipe
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
sort_by	String	Optional	This option will order results. Valid options include: newest, oldest, caloriesPerServingAscending, caloriesPerServingDescending. When not explicitly set, the ordering will be returned by newest
format	String	Optional	The desired response format. Valid response formats are "xml" or "json" (default value is "xml").

Premier Exclusive

Name	Type	Required	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 recipe_id.

Each recipes 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 recipe element contains information as follows:

NAME	TYPE	DESCRIPTION
recipe_id	Long	Unique recipe identifier
recipe_name	Long	Name of the recipe
recipe_description	String	A short description of the recipe
recipe_image	String	URL of this image on www.fatsecret.com

Each recipe_nutrition element contains information as follows:

NAME	TYPE	DESCRIPTION
calories	Decimal	Energy content in kcal
carbohydrate	Decimal	Total carbohydrate content in grams
protein	Decimal	Protein content in grams
fat	Decimal	Total fat content in grams

Each recipe_ingredients element contains information as follows:

NAME	TYPE	DESCRIPTION
ingredient	String	An ingredient in the recipe

Each recipe_types element contains information as follows:

NAME	TYPE	DESCRIPTION
recipe_type	String	Recipe type E.G.: "Appetizer"

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"?>
<recipes 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>1</total_results>
  <page_number>0</page_number>
  <recipe>
    <recipe_id>91</recipe_id>
    <recipe_name>Baked Lemon Snapper</recipe_name>
    <recipe_description>Healthy fish with a tasty sauce.</recipe_description>
    <recipe_image>http://www.fatsecret.com/static/recipe/bf0c5912-9cf8-4e7a-b07a-6703c4b77082.jpg</recipe_image>
    <recipe_nutrition>
      <calories>177</calories>
      <carbohydrate>2.23</carbohydrate>
      <protein>35.1</protein>
      <fat>2.32</fat>
    </recipe_nutrition>
    <recipe_ingredients>
      <ingredient>Lemon</ingredient>
      <ingredient>Snapper</ingredient>
    </recipe_ingredients>
    <recipe_types>
      <recipe_type>Main Dish</recipe_type>
    </recipe_types>
  </recipe>
</recipes>

Example 1:

{
  "recipes": {
    "max_results": "1",
    "page_number": "0",
    "recipe": {
      "recipe_description": "Healthy fish with a tasty sauce.",
      "recipe_id": "91",
      "recipe_image": "http://www.fatsecret.com/static/recipe/bf0c5912-9cf8-4e7a-b07a-6703c4b77082.jpg",
      "recipe_ingredients": {
        "ingredient": [
          "Lemon",
          "Snapper"
        ]
      },
      "recipe_name": "Baked Lemon Snapper",
      "recipe_nutrition": {
        "calories": "177",
        "carbohydrate": "2.23",
        "fat": "2.32",
        "protein": "35.1"
      },
      "recipe_types": {
        "recipe_type": "Main Dish"
      }
    },
    "total_results": "1"
  }
}

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>'
108	Parameter	Invalid Type: '<details>'