# 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](/api/recipes.md#data-structure).

## Endpoints


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.whisk.com/api/shopping-lists.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.