Recipes

The Recipes Sync API service provides you the ability to pull recipes individually or in a batch for data synchronization.

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": "1072689e47689e34a859633309c5d17fec8",
"name": "Grab-and-Go Breakfast Sandwich",
"description": "Skip the drive-thru. Your homemade breakfast sandwich, with cholesterol-free egg product, is better for you—and tastier!",
"instructions": {
...
},
"images":
[
...
],
"source": {
...
},
"servings": 1,
"durations": {
...
},
"ingredients": [
...
],
"normalized_ingredients": [
...
],
"nutrition": {
...
},
"labels": {
...
},
"author": {
...
},
"language": "en",
"updated_at_time": "1613754521094",
"created_at_time": "1613754521094",
"published_status": "RECIPE_PUBLISHED_STATUS_PUBLISHED"
"custom_labels": [
...
]
}

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

number

The number of people that can be served.

language

string

As per ISO 639 standards, a two-letter code indicating the language used in recipe definition.

updated_at_time

string

The last recipe update date and time in Unix format.

created_at_time

string

The recipe creation date and time in Unix format.

published_status

string

The recipe status. A recipe can have one of these supported status set here:

  • RECIPE_PUBLISHED_STATUS_DRAFT

  • RECIPE_PUBLISHED_STATUS_PUBLISHED

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.

‌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":[
{
"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.

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.

Deleted Recipe Object

Any recipes that you delete from Whisk Studio are marked as deleted and they appear as a deleted recipe when you pull recipes in batch using the Get Recipe Batch endpoint.

A deleted recipe object has the following data structure:

"deleted_recipe": {
"id": "107e25b932ca5a2484e8727e9e7cad8b2ca",
"deleted_at_time": "1610627213000",
"created_at_time": "1603990751339"
}

The deleted_recipe object contains the following attributes:

Attribute

Type

Description

id

string

The recipe identifier.

deleted_at_time

string

The recipe deletion date and time in Unix format.

created_at_time

string

The recipe creation date and time in Unix format.

Endpoints

Recipe API includes two endpoints that you can periodically use to pull recipe data from Whisk Studio.