Shopping List

The Shopping List API service offers you the ability to read and write your shopping list data.

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

Shopping List Object

A Shopping List object is a collection of arrays and child-objects that defines its data structure. This is how the data structure of a shopping list looks in JSON format:

{
"list": {
"id": "106f9105f1d05d24ad2b833f5d2a966be77",
"name": "My Shopping List"
},
"content": {
"items": [
{
"id": "d78b355d-110b-4b31-9f8b-fc221a7a7a3e",
"item": {
"name": "bacon",
"brand": "Oscar mayer",
"comment": "cooked, crumbled",
"quantity": 8,
"unit": "slices"
},
"checked": true,
"image_url": "https://whisk-res.cloudinary.com/image/upload/v1550764646/graph/fooddb/0919f5d46996479ba5575bcdc19dc0ba.jpg",
"analysis": {
"product": {
"canonical_name": "BACON",
"original_name": "bacon"
},
"category": {
"canonical_name": "MEATS AND SEAFOOD"
}
},
"recipe": {
"recipe_id": "1011f5a116db3c3e56e57bea0a52ffbfca5fc96f6b1",
"position": 5
},
"combined": {
"combined_item_id": "0ac9b296-9bb6-4043-a85a-02d64ae564b7",
"quantity": 1
},
"created_time": "1614175633",
"updated_at": "1614175806"
},
...
],
"combined_items": [
{
"id": "0ac9b296-9bb6-4043-a85a-02d64ae564b7",
"item": {
"name": "bacon",
"brand": "Oscar mayer",
"comment": "cooked, crumbled",
"quantity": 10,
"unit": "slices"
},
"checked": true,
"image_url": "https://whisk-res.cloudinary.com/image/upload/v1550764646/graph/fooddb/0919f5d46996479ba5575bcdc19dc0ba.jpg",
"analysis": {
"product": {
"canonical_name": "BACON",
"original_name": "bacon"
},
"category": {
"canonical_name": "MEATS AND SEAFOOD"
}
},
"created_time": "1614175633",
"updated_at": "1614175806"
}
],
"recipes": [
{
"id": "1011f5a116db3c3e56e57bea0a52ffbfca5fc96f6b1",
"name": "Bacon Cheeseburger Casserole",
"images": [
{
"responsive": {
"url": "https://whisk-res.cloudinary.com/image/upload/v1536910467/recipe/94f698dfcafefe3223aa66f1b3b21ae7.jpg",
"width": 428,
"height": 640
},
"url": "https://assets.kraftfoods.com/recipe_images/opendeploy/126725_MXM_K59919V0_OR1_CR_640x428.jpg"
}
],
"source": {
"name": "myfoodandfamily.com",
"display_name": "My Food and Family",
"source_recipe_url": "https://www.myfoodandfamily.com/recipe/126725/bacon-cheeseburger-casserole",
"image": {
"responsive": {
"url": "https://whisk-res.cloudinary.com/image/upload/v1565965713/publishers/logos/myfoodandfamily-logo.png",
"width": 256,
"height": 256
},
"url": "https://whisk-res.cloudinary.com/image/upload/v1565965713/publishers/logos/myfoodandfamily-logo.png"
},
"license": "LICENCE_FAIRUSE"
}
},
...
]
}
}

The following attributes define the core of a shopping list:

Attribute

Type

Description

list

object

It contains the shopping list name and identifier.

content

object

It contains details of the shopping list items and their related recipes.

list

The list object contains the shopping list identification details.

{
"list": {
"id": "106f9105f1d05d24ad2b833f5d2a966be77",
"name": "My Shopping List"
},

Attribute

Type

Description

id

string

The unique shopping list identifier.

name

string

The name of the shopping list.

content

The content object contains details of all the shopping list items and their source recipes.

"content": {
"items": [
...
],
"combined_items": [
...
],
"recipes": [
...
]
}

Attribute

Type

Description

items

array

A list of items added to the shopping list.

combined_items

array

A list of similar items combined to appear as a single item in the shopping list (if any).

recipes

array

A list of recipes that included the items added to the shopping list.

items

The items array stores information on each item that your shopping list contains.

"items": [
{
"id": "d78b355d-110b-4b31-9f8b-fc221a7a7a3e",
"item": {
...
},
"checked": true,
"image_url": "https://whisk-res.cloudinary.com/image/upload/v1550764646/graph/fooddb/0919f5d46996479ba5575bcdc19dc0ba.jpg",
"analysis": {
...
},
"recipe": {
...
},
"combined": {
...
},
"created_time": "1614175633",
"updated_at": "1614175806"
},
...
],

The data structure of each list item contains the following attributes:

Attribute

Type

Description

id

string

The unique identifier of the list item.

item

object

It contains the item's reference and measurement details.

checked

boolean

It indicates if the item is checked or unchecked in the shopping list.

image_url

string

The URL of the item's image.

analysis

object

​Additional reference details of the item.

recipe

object

It contains information on the source recipe that included the item as an ingredient.

combined

object

If the current item is merged with similar items in the shopping list, this array contains information on the resulted combined item in the shopping list.

created_time

string

Date and time in Unix format indicating the item's creation date.

updated_at

string

Date and time in Unix format indicating the time when the item was last updated.

item

The item object contains attributes related to the item's credentials and required quantity.

"item":{
"name":"bacon",
"brand":"Oscar mayer",
"comment":"cooked, crumbled",
"quantity":8,
"unit":"slices"
},

Attribute

Type

Description

name

string

The item's name.

brand

array

The brand name if the item is of a specific brand.

comment

boolean

Additional information attached with the item.

quantity

number

The item's volume or count.

unit

array

The measurement unit of the item's quantity.

analysis

The analysis object includes additional information on the item saved in the database.

"analysis":{
"product":{
"canonical_name":"ONION",
"original_name":"onion"
},
"category":{
"canonical_name":"FRUITS AND VEGETABLES"
}
},

Attribute

Type

Description

product

object

It contains information on the canonical and original name of the item as stored in the Whisk database.

category

object

The name of the category to which the item belongs.

recipe

The recipe object stores reference of the source recipe that included the item as an ingredient when it was added to the shopping list.

"recipe":{
"recipe_id":"1011f5a116db3c3e56e57bea0a52ffbfca5fc96f6b1",
"position":5
},

Attribute

Type

Description

recipe_id

string

The source recipe's identifier.

position

number

The item's position in the recipe's ingredient list.

combined

The combined object includes reference of the combined item in which the current item has been merged.

"combined":{
"combined_item_id":"0ac9b296-9bb6-4043-a85a-02d64ae564b7",
"quantity":1
},

Attribute

Type

Description

combined_item_id

string

The combined item's identifier.

quantity

number

The current item's volume or count added to the combined item quantity.

combined_items

"combined_items":[
{
"id":"0ac9b296-9bb6-4043-a85a-02d64ae564b7",
"item":{
...
},
"checked":true,
"image_url":"https://whisk-res.cloudinary.com/image/upload/v1550764646/graph/fooddb/0919f5d46996479ba5575bcdc19dc0ba.jpg",
"analysis":{
...
},
"created_time":"1614175633",
"updated_at":"1614175806"
}
],

The combined_items array includes detailed information of each combined item that exists in the shopping list as a result of merging similar items. A combined item's data structure is identical to the data structure of its original item. However, the quantity attribute inside the item array stores a cumulative quantity of all merged items.

recipes

The recipes array contains details of each recipe that was used a source to add items to the shopping list.

"recipes":[
{
"id":"1011f5a116db3c3e56e57bea0a52ffbfca5fc96f6b1",
"name":"Bacon Cheeseburger Casserole",
"images":[
{
"responsive":{
"url":"https://whisk-res.cloudinary.com/image/upload/v1536910467/recipe/94f698dfcafefe3223aa66f1b3b21ae7.jpg",
"width":428,
"height":640
},
"url":"https://assets.kraftfoods.com/recipe_images/opendeploy/126725_MXM_K59919V0_OR1_CR_640x428.jpg"
}
],
"source":{
"name":"myfoodandfamily.com",
"display_name":"My Food and Family",
"source_recipe_url":"https://www.myfoodandfamily.com/recipe/126725/bacon-cheeseburger-casserole",
"image":{
"responsive":{
"url":"https://whisk-res.cloudinary.com/image/upload/v1565965713/publishers/logos/myfoodandfamily-logo.png",
"width":256,
"height":256
},
"url":"https://whisk-res.cloudinary.com/image/upload/v1565965713/publishers/logos/myfoodandfamily-logo.png"
},
"license":"LICENCE_FAIRUSE"
}
},
...
]

The data structure of each recipe contains the following attributes:

Attribute

Type

Description

id

string

The recipe identifier.

name

string

The full name of the recipe.

images

array

It contains details of the recipe's images.

source

object

It contains details of the recipe origins.

Each of these recipe attributes are covered in the detail in the Recipe API Service.

Endpoints