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
​
Remove Collection
Get your Shopping Lists
Last updated 2 months ago
Shopping List

Shopping List Object

`list`

`content`

`items`

`combined_items`

`recipes`

Endpoints

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.
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.