Recipes: Search v2

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.

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.

Parameters

Required

Name Type Description
method String MUST be "recipes.search.v2"

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 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
calories.to Decimal The maximum calories that are contained in the recipe
carb_percentage.from Long The minimum percentage of the calories composed of carbohydrate
carb_percentage.to Long The maximum percentage of the calories composed of carbohydrate
protein_percentage.from Long The minimum percentage of the calories composed of protein
protein_percentage.to Long The maximum percentage of the calories composed of protein
fat_percentage.from Long The minimum percentage of the calories composed of fat
fat_percentage.to 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
prep_time.to 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

Response

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="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 Return JSON

{ "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 Code

Code Description
13 Invalid token: "<detail>"
107 Value out of range: "<detail>"
108 Invalid Type: "<detail>"
FatSecret Sites
For Developers

For Professionals

For Everyone

FatSecret Platform API

Developers

Support
API

About FatSecret

© 2023 FatSecret. All rights reserved.