Recipes: Search v2


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.

The only storable values returned by this call are the recipe_id unique recipe identifiers of each recipe matching the search expression.

Why are we introducing this version?

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.

Localization (Premier Only):

One additional optional parameter named region is available to premier clients. More information can be found in the Localization guide.



Name Type Description
oauth_consumer_key String Your API key when you registered as a developer
oauth_signature_method String The method used to generate the signature (only HMAC-SHA1 is supported)
oauth_timestamp Int The date and time, expressed in the number of seconds since January 1, 1970 00:00:00 GMT. The timestamp value must be a positive integer and must be equal or greater than the timestamp used in previous requests
oauth_nonce String A randomly generated string for a request that can be combined with the timestamp to produce a unique value
oauth_version String MUST be "1.0"
oauth_signature String The signature, a consistent reproducible concatenation of the request elements into a single string. The string is used as an input in hashing or signing algorithms.
method String MUST be ""


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 recipe names and ingredients.
must_have_images Bool This option will restrict results to recipes with at least one image
calories.from Decimal The minimum calories that are contained in the recipe Decimal The maximum calories that are contained in the recipe
carb_percentage.from Long The minimum percentage of the calories composed of carbohydrate Long The maximum percentage of the calories composed of carbohydrate
protein_percentage.from Long The minimum percentage of the calories composed of protein Long The maximum percentage of the calories composed of protein
fat_percentage.from Long The minimum percentage of the calories composed of fat Long The maximum percentage of the calories composed of fat
prep_time.from Long The minimum preparation and cook time in minutes required to create the recipe Long The maximum preparation and cook time in minutes required to create the recipe
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.
sort_by String This option will order results. Valid options include: newest, oldest, caloriesPerServingAscending, caloriesPerServingDescending. When not explicitly set, the ordering will be returned by newest


The recipe elements returned are those best matching the search expression specified, ordered by their relevancy to the search expression.

Each recipe element contains summary information about the recipe item as follows:

  • recipe_id – the unique recipe identifier.
  • recipe_name – the name of the recipe.
  • recipe_description – A short description of the recipe.
  • recipe_image – URL of this recipe item's default image, only if this is available

Nutrient values for each recipe item are returned according to a single serving - see nutrient

Ingredients for each recipe item

  • ingredient is a String – an ingredient in the recipe.
Recipe types for each recipe item

  • recipe_type is a String – a tag for the recipe for identification and classification. e.g. Main Dish

Example Return XML

<?xml version="1.0" encoding="utf-8" ?>
<recipes xmlns="" xmlns:xsi="" xsi:schemaLocation="">
        <recipe_name>Baked Lemon Snapper</recipe_name>
        <recipe_description>Healthy fish with a tasty sauce.</recipe_description>
            <recipe_type>Main Dish</recipe_type>

Example Return JSON

{ "recipes": {"max_results": "1", "page_number": "0", "recipe": {"recipe_description": "Healthy fish with a tasty sauce.", "recipe_id": "91", "recipe_image": "http:\/\/\/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 Code

Code Description
2 Missing required oauth parameter: "<detail>"
3 Unsupported oauth parameter: "<detail>"
4 Invalid signature method: "<detail>"
5 Invalid consumer key: "<detail>"
6 Invalid/expired timestamp: "<detail>"
7 Invalid/used nonce: "<detail>"
8 Invalid signature: "<detail>"
107 Value out of range: "<detail>"
108 Invalid Type: "<detail>"
FatSecret Sites
For Developers

For Professionals

For Everyone

FatSecret Platform API



About FatSecret

© 2023 FatSecret. All rights reserved.