# Shopping List

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:

```javascript
{
  "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://image-cdn.whisk.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://image-cdn.whisk.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://image-cdn.whisk.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://image-cdn.whisk.com/image/upload/v1565965713/publishers/logos/myfoodandfamily-logo.png",
              "width": 256,
              "height": 256
            },
            "url": "https://image-cdn.whisk.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.

```javascript
{
  "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.

```javascript
  "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.

```javascript
    "items": [
      {
        "id": "d78b355d-110b-4b31-9f8b-fc221a7a7a3e",
        "item": {
          ...
        },
        "checked": true,
        "image_url": "https://image-cdn.whisk.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.

```javascript
"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.

```javascript
"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.

```javascript
"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.

```javascript
"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`

```javascript
"combined_items":[
   {
      "id":"0ac9b296-9bb6-4043-a85a-02d64ae564b7",
      "item":{
         ...
      },
      "checked":true,
      "image_url":"https://image-cdn.whisk.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.

```javascript
"recipes":[
   {
      "id":"1011f5a116db3c3e56e57bea0a52ffbfca5fc96f6b1",
      "name":"Bacon Cheeseburger Casserole",
      "images":[
         {
            "responsive":{
               "url":"https://image-cdn.whisk.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://image-cdn.whisk.com/image/upload/v1565965713/publishers/logos/myfoodandfamily-logo.png",
               "width":256,
               "height":256
            },
            "url":"https://image-cdn.whisk.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](https://docs.whisk.com/recipes#data-structure).

## Endpoints