Recipe

The Recipe API service lets you read and write any internal and external recipes and your Whisk recipe collections.

Let's first understand the Recipe object and its data structure before looking at its endpoints' description.

Recipe Object

A Recipe object is a collection of arrays and attributes that defines the data structure for any given recipe.

This is how the data structure of a recipe looks in JSON format:

{
  "recipe": {
    "id": "107d918699fb79c4ed4a561823f9f77d64e",
    "name": "Blueberry Bakewell muffins",
    "description": "These easy blueberry muffins have a delightfully jammy centre and crunchy crumble topping - a tasty treat for teatime or packed lunch",
    "ingredients": [
      ...
    ],
    "instructions": {
      ...
    },
    "images": [
      ...
    ],
    "videos": [
      ...
    ],
    "source": {
      ...
    },
    "servings": 12,
    "servings_scaled": 2,
    "durations": {
      ...
    },
    "normalized_ingredients": [
      ...
    ],
    "nutrition": {
      ...
    },
    "labels": {
      ...
    },
    "constraints": {
      ...
    },
    "saved": {
      ...
    },
    "author": {
      ...
    },
    "language": "en",
    "custom_labels": [
      ...
    ],
    "main_ingredients": [
      ....
    ]
  }
}

Core Attributes

The following attributes define the core of a recipe:

Attribute	Type	Description
id	string	The recipe identifier.
name	string	The full name of the recipe.
description	string	A summary describing the recipe.
servings	integer	The number of people that can be served the original recipe.
servings_scaled	integer	The number of servings based on the requirement you specified while pulling the recipe details.
language	string	As per ISO 639 standards, a two-letter code indicating the language used in recipe definition.

In addition to the base attributes, there are objects and arrays that contain more information on the recipe.

Ingredients

This array contains information on the ingredients used in the recipe.

"ingredients":[
   {
      "text":"1/4 cup cholesterol-free egg product"
   },
   ...
   {
      "text":"HEINZ Tomato Ketchup",
      "linked_product":{
         "id":"5f75d73bcfed282362a8b3aa",
         "name":"HEINZ Tomato Ketchup",
         "images":[
            ...
         ]
      }
   }
],

Attribute	Type	Description
text	string	A specific ingredient used in the recipe — sugar 2-tbsp, flour 10g, or garlic 3-cloves.
group	string	The group name if the ingredient falls under a particular group of ingredients.
linked_product	object	This object contains details of a branded product that is stored in Whisk Studio and is being used as an ingredient.

The linked_product object contains the following attributes:

Attribute	Type	Description
id	string	The product identifier.
name	string	The product’s full name.
images	array	One or more images of the product. This array contains the hosted URL and size details of each product image.
external_product_id	string	An identifier assigned by the product's author.

Images

This array contains information on one or more images of the completed dish included in the recipe.

"images":[
   {
      "url":"https://whisk-res.cloudinary.com/image/upload/v1603979937/recipe/a322bb09c8934e66d3eca3f98c59004a.jpg",
      "responsive":{
         "url":"https://whisk-res.cloudinary.com/image/upload/v1603979937/recipe/a322bb09c8934e66d3eca3f98c59004a.jpg",
         "width":240,
         "height":208
      }
   },
   ...
],

Attribute	Type	Description
url	string	Hosted URL of an image.
responsive	object	A responsive image adjusts its size based on the screen size. This object contains attributes to access the image with flexible size based on need.

The responsive object contains the following attributes:

Attribute	Type	Description
url	string	Hosted URL of an image.
width	number	Image width.
height	number	Image height.

Source

‌This object contains details of the recipe origins.

"source":{
    "name":"myfoodandfamily.com",
    "display_name":"myfoodandfamily",
    "url":"https://www.myfoodandfamily.com/recipe/063765/grab-and-go-breakfast-sandwich?utm=skforu_rdp",
    "image":{
                "url":"https://whisk-res.cloudinary.com/image/upload/v1565965713/publishers/logos/myfoodandfamily-logo.png",
        "responsive":{
            "url":"https://whisk-res.cloudinary.com/image/upload/v1565965713/publishers/logos/myfoodandfamily-logo.png",
            "width":256,
            "height":256
        }
    }
},

Attribute	Type	Description
name	string	Indicates the name of the recipe’s origin.
display_name	string	Indicates the display name of the recipe's origin.
url	string	The recipe’s origin URL.
image	object	This object includes information on the origins of the recipe's image.

Durations

‌This object contains information on the time it takes to prepare and cook the recipe.

"durations":{
    "cook_time":20,
    "prep_time":10,
    "total_time":30
},

Attribute	Type	Description
cook_time	number	The time (in minutes) it takes to cook the dish.
prep_time	number	The time (in minutes) it takes to prepare the items used in the recipe's instructions.
total_time	number	The total time (in minutes) it takes to prepare the dish.

‌Labels

‌‌This object contains information on the labels attached to the recipe that helps distinguish its type, cuisine, category, and the techniques required to cook.

"labels": {
    "meal_type": [
      {
        "name": "main-course",
        "display_name": "Main Course"
      },
      ...

      {
        "name": "dinner",
        "display_name": "Dinner"
      }
    ],
    "cuisine": [
      {
        "name": "french",
        "display_name": "French"
      }
    ],
    "category": [
      {
        "name": "dinner",
        "display_name": "Dinner"
      },
      {
        "name": "lunch",
        "display_name": "Lunch"
      }
    ],
    "technique": [
      {
        "name": "simmering",
        "display_name": "Simmering"
      },
      ...

      {
        "name": "pan-frying",
        "display_name": "Pan Frying"
      }
    ]
  },

Each label attached to the recipe appears as a child-array.

Attribute	Type	Description
meal_type	array	Indicates the meal type that applies to the recipe.
cuisine	array	Indicates the recipe's cuisine.
category	array	Indicates the recipe's category.
technique	array	Indicates the cooking technique required to cook the recipe.

Each of these arrays contains the following attributes:

Attribute	Type	Description
name	string	​The label name saved in the source.
display_name	string	The label name that appears on the front-end.

For information on supported labels, see Recipe Labels.

Author

‌This object includes information about the Whisk user who created the recipe.

"author":{
    "id": "10297e19d97dd5a43ecbd9a13172ce65bfb"
    "name":"Sara Buenfeld"
    "image":{
      "url":"https://img.cjthemarket.com/images/file/author/973/20191226105710715.jpg",
      "responsive":{
         "url":"https://whisk-res.cloudinary.com/image/upload/v1602854082/author/8bade35e90ecf44eac6ec7ae5346d228.jpg",
         "width":300,
         "height":300
      }
},

Attribute	Type	Description
id	string	The recipe creator's identifier.
name	string	The recipe creator's name.
image	object	The recipe creator's image. See the images array description for more information.

Custom Labels

‌This array includes a list of user-defined labels linked to the recipe.

"custom_labels":[
   {
      "name":"brand-category",
      "labels":[
         {
            "name":"cj-chinese"
         },
         {
            "name":"cj-etc"
         }
      ]
   },
   {
      "name":"brand",
      "labels":[
         {
            "name":"kraft-cheese"
         }
      ]
   },
   {
      "name":"barcode-number",
      "labels":[
         {
            "name":"00013000006409"
         }
      ]
   }
]

Attribute	Type	Description
name	string	Label group's name.
labels	array	A list of labels inside the group.

Tips

‌This array includes a list of advice linked to the recipe.

 "tips": [
    {
      "header": "string",
      "text": "string"
    }
 ]

Type	Type	Description
header	string	A heading for the advice.
text	string	Text describing the advice.

Main ingredients

The most important products of a recipe. We consider them to be equal in case there are several products returned.

 "main_ingredients": [
      "veal",
      "bacon",
      "fruit"
]

Optional Data

The recipe data structure may include extra information based on any additional parameters included in the API request.

Normalized Ingredients

This array includes detailed analysis of each recipe's ingredient.

"normalized_ingredients":[
   {
      "text":"1 slice cooked OSCAR MAYER Bacon, cut crosswise in half",
      "analysis":[
         {
            "alternative_measurements": [
                        {
                            "amount": {
                                "quantity": 120,
                                "unit": "g"
                            },
                            "measurement_system": "MEASUREMENT_SYSTEM_METRIC"
                        },
                        {
                            "amount": {
                                "quantity": 1,
                                "unit": "slice"
                            },
                            "measurement_system": "MEASUREMENT_SYSTEM_IMPERIAL"
                        }
                    ],
            "product":{
               "canonical_name":"OSCAR MAYER COOKED BACON (READY MADE)",
               "original_name":"cooked oscar mayer bacon"
            },
            "category":{
               "canonical_name":"MEATS AND SEAFOOD"
            },
            "brand":{
               "canonical_name":"OSCAR MAYER"
            },
            "quantity":1,
            "unit":"slice",
            "comment":"cut crosswise in half",
            "image_url":"https://whisk-res.cloudinary.com/image/upload/v1570185262/custom_upload/4e3434d390926ff30a3f96652529194d.jpg"
         }
      ],
      "source_text":"1 slice cooked OSCAR MAYER Bacon, cut crosswise in half"
   },
   {
      "text":"HEINZ Tomato Ketchup",
      "linked_product":{
         "id":"5f75d73bcfed282362a8b3aa",
         "name":"HEINZ Tomato Ketchup",
         "images":[
            {
               "url":"https://whisk-res.cloudinary.com/image/upload/v1600195675/inventory_item/20c81dcc9b003de383b1891828b59fc5.jpg"
            }
         ]
      },
      "source_text":"HEINZ Tomato Ketchup"
   },
   ...
],

Attribute	Type	Description
text	string	A specific ingredient used in the recipe — sugar 2-tbsp, flour 10g, or garlic 3-cloves.
group	string	The group name if the ingredient falls under a particular group of ingredients.
linked_product	object	This object contains details of a branded product that is stored in Whisk Studio and is being used as an ingredient. For more information, see the ingredients array.
analysis	array	​Detailed information on the ingredient that is not linked to any product stored in Whisk Studio.
source_text	string	​The ingredient name saved in the source.

The analysis array includes the following attributes:

Attribute	Type	Description
product	object	The canonical and original name of the product being used as an ingredient. It should not be confused with the linked_product object, since specific recipes may specify a branded product as an ingredient, which may not be one of their own branded products on Whisk Studio.
alternative_measurements	object	The alternative measurment unit for ingredient. Contains metric and imperial units and measurments
category	object	The canonical name of the category to which the ingredient belongs.
brand	object	The ingredient product's brand canonical name.
quantity	number	The ingredient volume or count.
comment	string	Any additional info attached with the ingredient.
unit	string	The measurement unit of the ingredient's quantity.
multiplier	number	​The factor for unit conversion.
image_url	string	The source location of the ingredient's image.

‌Instructions‌

This object includes information on each step required in the recipe preparation.

"instructions":{
   "steps":[
      {
         "text":"Cook egg product in skillet sprayed with cooking spray on medium heat 3 min. or until set, stirring occasionally.",
         "images":[
            {
               "url":"https://whisk-res.cloudinary.com/image/upload/v1603979936/recipe/33c0f4a5c00651929f57d00b398aafda.jpg",
               "width":424,
               "height":640
            }
         ]
      },
      {
         "text":"Fill muffin halves with egg product, Singles and bacon.",
         "images":[
            {
               "url":"https://whisk-res.cloudinary.com/image/upload/v1603979947/recipe/62848f0ee14fd5808e541e3e29934e72.jpg",
               "width":424,
               "height":640
            }
         ]
      }
   ]
},

Attribute	Type	Description
steps	array	An array containing a list of steps required to cook the recipe.

The steps array contains the following attributes:

Attribute	Type	Description
text	string	A specific step in the list of instructions to cook the recipe — “Heat the oil in a large frying pan”.
group	string	The group name if the step falls under a particular group of steps.
images	array	One or more images attached to the step. This array contains the hosted URL and size details of each image.
custom_labels	array	One or more user-defined labels attached to the step. For more information, see the custom labels array.

Nutrition

‌This object contains information about the recipe's nutritional value.

"nutrition":{
    "status":"STATUS_AVAILABLE",
    "total":[
        {
            "label":"Magnesium",
            "code":"NUTRITION_CODE_MG",
            "value":82.61800000000001,
            "unit":"NUTRITION_UNIT_MG"
        },
        ...
    ],
    "coverage": 0.93,
    "health_score":{
        "value":6.687124447756711,
        "nutrients_influence":[
            {
                "code":"NUTRITION_CODE_FAT_UNSAT",
                "influence":0.7762592808559045,
                "comment":"Strong positive impact"
            },
            ...
        ]
    },
    "glycemic_index":{
        "value":42.12
    },
    "glycemic_load":{
        "value":7.66
    }
},

Attribute	Type	Description
status	string	The recipe's nutritional information availability status.
total	array	This array contains a detailed analysis of nutrients available in the recipe.
coverage	string	A value between 0-1 to indicate the extent of analysis done while calculating the nutritional facts.
health_score	object	The recipe's health score and analysis.
glycemic_index	object	The glycemic index is a value that indicates the recipe's impact on blood glucose levels.
glycemic_load	object	The glycemic load is a value that indicates the recipe's impact on blood sugar levels.

Each object contains additional attributes.

‌Total

‌This array contains information about the nutrients available in the recipe. Each nutrient carries the following information:

Attribute	Type	Description	Example
code	enum	The nutrient code.	NUTRITION_CODE_MG
label	string	The name of the nutrient.	Magnesium
value	integer	The nutrient's value/amount.	82.61800000000001
unit	enum	The measurement unit of the nutrient's value.	NUTRITION_UNIT_G NUTRITION_UNIT_MG NUTRITION_UNIT_MKG NUTRITION_UNIT_KCAL

‌Health Score

‌This array contains information on the health score assigned to the recipe.

Attribute	Type	Description
value	double	​The health score assigned to the recipe.
nutrients_influence	array	The components based on which the health score is derived.

‌Glycemic Index

‌This array includes information on the glycemic index score assigned to the recipe. It helps in understanding the impact of the recipe on blood sugar levels.

Attribute	Type	Description
value	double	The ​glycemic index score.

‌Glycemic Load

‌This array includes information on the glycemic load score assigned to the recipe. It helps in understanding the impact of the recipe on blood glucose levels.

Attribute	Type	Description
value	double	​The glycemic load score.