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