FatSecret Platform API Documentation

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.

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

Why are we introducing this version?

Updated json array formatting so it is consistent when one object is returned.

This version supports filtering by recipe types.

Parameters

URL / Method

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

Additional Parameters

NAME	TYPE	REQUIRED	DESCRIPTION
recipe_types	String	Optional	This option filters by specified recipe types and should be provided as a comma separated string of recipe type names. The values are provided via the api: Recipe Types Get All
recipe_types_matchall	Bool	Optional	This option will affect recipe type filters. If true, a recipe must match all provided recipe types, if false (default) then recipes matching any of the supplied types will be returned, The values are provided via the api: Recipe Types Get All
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	Long	Optional	Minimum calories that are contained in the recipe
calories.to	Long	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	String	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

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>