# Recipe Feed

| GET | `/v1/feed` |
| --- | ---------- |

This endpoint provides a Feed that can contain Recipes by default and other types of items on demand.

## Pagination

We use cursor-based pagination, you can read more about it here: [cursor pagination](https://docs.whisk.com/master/master#cursor-pagination).

Each request without specifying cursors will create a new feed thread with a unique id which you can find in response. While you use cursors you will traverse by one thread and there will not be any duplicates. We do not ensure that you will get the same items in different feed threads.

You can get the same feed using a feed identifier in query parameters (`id=...`).

It can be useful when you want to iterate by the same feed (e.g. When a user updates page or opens app shortly after the first visit.).

The feed is created for 12 hours after that, you will get a new feed, even if you use the same feed identifier.

## Personalization

If [user token](https://docs.whisk.com/master/api/auth/user-access-token)[ ](https://developers.whisk.com/docs/authentication/user-access-token)is used, user properties will be considered in resulting feed e.g [diets](https://docs.whisk.com/master/resources/recipe-labels#diets) and [avoidances](https://docs.whisk.com/master/resources/recipe-labels#avoidances).

Also, we consider region in feed items calculations. Country code will be retrieved from user settings if a user token is used. Or you can force country in feed request parameters.

## Feed content

We provide different types of feed content. By default, it is the only `recipe`but you can specify other types in parameter `allowedTypes.`

### Tags

Feed items can be marked with [tag](#tags):

* `healthy`- healthy recipes
* `dinners`- recipes for dinners
* `easyDinners`- quick and easy recipes for dinners
* trending - trending recipes based on recipe impressions

### Feed groups

A feed can include groups that users can navigate to and view content inside.

```javascript
{
  "type": "group",
  "key": {
    "id": "category::appetizers-and-snacks"
  },
  "display": {
    "displayName": "Appetizers and Snacks",
    "images": [
      "..."
    ]
  },
  "content": {
    "id": "appetizers-and-snacks",
    "displayName": "Appetizers and Snacks",
    "groupType": "category"
  },
  "filterKey": "category::appetizers-and-snacks"
}
```

To get content for the specific group you need to provide `filterKey`in feed query param alongside feed `id`.

Example:

```bash
filterKey=category::bbq-and-grilling
```

(`filterKey` should be extracted from group `filterKey`field)

#### Example of feed group usage:

The goal is to show items related to one specific group.

**Step 1:** You can get a regular feed with groups:

```bash
curl "https://graph.whisk.com/v1/feed?limit=5&allowedContent=recipe,group" \
  -H "Accept: application/json" \
  -H "Authorization: Token <Access-Token>"
```

**Step 2:** If the user clicks on one of the group items in the feed, you can get specific feed for items related to this group. All you need is pass field `filterKey`from group FeedElement into `filterKey`parameter of a feed request.

```bash
curl "https://graph.whisk.com/v1/feed?limit=5&id=asd080345473dda9394e6e76d92c369u&filterKey=category::bbq-and-grilling" \
  -H "Accept: application/json" \
  -H "Authorization: Token <Access-Token>"
```

Tip: Feed API can be used to implement rotation for featured recipes. You can specify the size of the feed and rotate items using provided cursors in the required timing.

## Parameters

| ATTRIBUTE          | TYPE            | DESCRIPTION                                                                                          |
| ------------------ | --------------- | ---------------------------------------------------------------------------------------------------- |
| limit              | integer         | This is the maximum number of objects that may be returned Default value: 16                         |
| before             | string          | This is the cursor to return data on a page before it.                                               |
| after              | string          | This is the cursor to return data from the next page.                                                |
| id                 | string          | Feed identifier                                                                                      |
| userId             | string          | Whisk user identifier, allows considering user settings (e.g. diets and allergies) in feed results.  |
| country            | string          | Country in ISO 3166-1 alpha-2 format e.g. GB, US, ... Default value: GB                              |
| language           | string          | Language in ISO 639-1 format e.g. en, it, de ... Default value: en                                   |
| allowedContent     | array           | List of feed types Possible values: recipe, link, group. Default value: recipe                       |
| labels             | array \[string] | how to use labels                                                                                    |
| excludeIngredients | array \[string] | recipes should not have any of these ingredients                                                     |
| filterKey          | string          | Filter by a group allows getting items related to specific groups. Example: category::quick-and-easy |
| tags               | array           | List of feed recommendation tags Possible values: easyDinners, dinners, trending, healthy.           |
| fields             | array \[string] | Extra fields to return on the recipe                                                                 |

## FeedResponse

| ATTRIBUTE | TYPE                 | DESCRIPTION            |
| --------- | -------------------- | ---------------------- |
| id\*      | string               | Unique feed identifier |
| feed\*    | array \[FeedElement] |                        |
| paging\*  | Paging               |                        |

### FeedElement

Element of the Feed

| ATTRIBUTE | TYPE            | DESCRIPTION                                                                                        |
| --------- | --------------- | -------------------------------------------------------------------------------------------------- |
| type\*    | string          | type of feed element                                                                               |
| key\*     | FeedItemKey     | key to identify Feed element. Used when submit feed impressions                                    |
| display   | FeedItemDisplay | contains generic information related to displaying FeedElement                                     |
| content\* | one of          | Possible types: FeedRecipeContent, FeedCategoryContent, FeedLinkContent, Discriminator field: type |
| filterKey | string          | key to fetch content inside group. see filterKey feed query parameter                              |

### Paging

| ATTRIBUTE | TYPE    | DESCRIPTION |
| --------- | ------- | ----------- |
| cursors\* | Cursors |             |

### Cursors

| ATTRIBUTE | TYPE   | DESCRIPTION |
| --------- | ------ | ----------- |
| after     | string |             |
| before    | string |             |

### FeedItemKey

| ATTRIBUTE | TYPE   | DESCRIPTION                    |
| --------- | ------ | ------------------------------ |
| id\*      | string | Unique feed element identifier |

### FeedItemDisplay

Sufficient information to display feed item.

| ATTRIBUTE     | TYPE            | DESCRIPTION |
| ------------- | --------------- | ----------- |
| displayName\* | string          |             |
| images\*      | array \[string] |             |
| tag           | FeedItemTag     |             |

### FeedItemTag

| ATTRIBUTE   | TYPE            | DESCRIPTION                                               |
| ----------- | --------------- | --------------------------------------------------------- |
| name\*      | array           | Possible values: easyDinners, dinners, trending, healthy. |
| displayName | string          | readable name                                             |
| image       | ResponsiveImage |                                                           |

### FeedGroupContent

| ATTRIBUTE     | TYPE   | DESCRIPTION                                                                          |
| ------------- | ------ | ------------------------------------------------------------------------------------ |
| id\*          | string | unique group identifier                                                              |
| displayName\* | string | Readable group name                                                                  |
| groupType\*   | enum   | Can be category provided by Whisk or custom group Possible values: category, custom. |

### FeedLinkContent

| ATTRIBUTE     | TYPE   | DESCRIPTION            |
| ------------- | ------ | ---------------------- |
| id\*          | string | unique link identifier |
| displayText\* | string | link text              |
| url\*         | string | link URL               |

### FeedRecipeContent

| ATTRIBUTE   | TYPE                    | DESCRIPTION                                                            |
| ----------- | ----------------------- | ---------------------------------------------------------------------- |
| id\*        | string                  |                                                                        |
| name\*      | string                  |                                                                        |
| description | string                  |                                                                        |
| author      | RecipeAuthor            |                                                                        |
| images      | array \[ImageContainer] |                                                                        |
| videos      | array \[VideoContainer] |                                                                        |
| source\*    | RecipeSource            |                                                                        |
| saved       | RecipeSaved             | This field is populated if fields=saved is added to request parameters |

### ImageContainer

| ATTRIBUTE    | TYPE            | DESCRIPTION                                                       |
| ------------ | --------------- | ----------------------------------------------------------------- |
| url\*        | string          | original image url, depricated. Please use field original instead |
| original     | OriginalImage   | original image information, e.g. image url                        |
| responsive\* | ResponsiveImage |                                                                   |

### VideoContainer

| ATTRIBUTE  | TYPE   | DESCRIPTION                                         |
| ---------- | ------ | --------------------------------------------------- |
| url        | string | URL to original video provider page                 |
| contentUrl | string | URL to video file. Actual bytes of the media object |
| embedUrl   | string | An embed format of video with player                |
| playerType | enum   | Possible values: flash, html5, silverlight.         |
| thumbnail  | string | A thumbnail image relevant to the Video             |
| duration   | number | The duration of the recording                       |
| height     | number | The height of the item                              |
| width      | number | The width of the item                               |

### RecipeSource

| ATTRIBUTE       | TYPE           | DESCRIPTION |
| --------------- | -------------- | ----------- |
| name\*          | string         |             |
| displayName     | string         |             |
| sourceRecipeUrl | string         |             |
| license         | string         |             |
| image           | ImageContainer |             |

### ResponsiveImage

| ATTRIBUTE | TYPE    | DESCRIPTION            |
| --------- | ------- | ---------------------- |
| url\*     | string  | Hosted url of an image |
| width\*   | integer | Image width            |
| height\*  | integer | Image height           |

### RecipeAuthor

| ATTRIBUTE | TYPE           | DESCRIPTION |
| --------- | -------------- | ----------- |
| name\*    | string         |             |
| image     | ImageContainer |             |

### RecipeSaved

| ATTRIBUTE     | TYPE            | DESCRIPTION                                    |
| ------------- | --------------- | ---------------------------------------------- |
| value         | boolean         | True if this recipe is saved to favorites      |
| collectionIds | array \[string] |                                                |
| owner         | boolean         | If current user is owner of the recipe         |
| type          | enum            | Recipe type Possible values: manual, imported. |

### Sample Request

```bash
curl "https://graph.whisk.com/v1/feed?limit=5&allowedContent=link,group,recipe" \
    -H "Accept: application/json" \
    -H "Authorization: Token <Access-Token>"
```

### Sample Response

```javascript
{
  "id": "301d1456411e4082af0e37d12ef5ec49",
  "feed": [
    {
      "type": "group",
      "key": {
        "id": "category::appetizers-and-snacks"
      },
      "display": {
        "displayName": "Appetizers and Snacks",
        "images": [
          {
            "url": "https://whisk-res.cloudinary.com/image/upload/v1524060217/graph/categories/world/Appetizers_and_Snacks.jpg",
            "responsive": {
              "url": "https://whisk-res.cloudinary.com/image/upload/v1524060217/graph/categories/world/Appetizers_and_Snacks.jpg",
              "width": 800,
              "height": 800
            }
          }
        ]
      },
      "content": {
        "id": "appetizers-and-snacks",
        "displayName": "Appetizers and Snacks",
        "groupType": "category"
      },
      "filterKey": "category::appetizers-and-snacks"
    },
    {
      "type": "link",
      "key": {
        "id": "link::16eba08da247483db6437f8391e0fd48"
      },
      "display": {
        "displayName": "Check out a smart Whisk platform.",
        "images": [
          {
            "url": "https://whisk-res.cloudinary.com/image/upload/v1526474016/custom_upload/abfa740e034f71b60a769dcdbad22a68.jpg",
            "responsive": {
              "url": "https://whisk-res.cloudinary.com/image/upload/v1526474016/custom_upload/abfa740e034f71b60a769dcdbad22a68.jpg",
              "width": 1042,
              "height": 938
            }
          }
        ],
        "tag": {
          "name": "partners",
          "displayName": "Partners"
        }
      },
      "content": {
        "id": "16eba08da247483db6437f8391e0fd48",
        "displayText": "Check out a smart Whisk platform.",
        "url": "https://recipes.whisk.com/feed"
      }
    },
    {
      "type": "recipe",
      "key": {
        "id": "recipe::9847a3d1ca5d11e7ae7e42010a9a0035"
      },
      "display": {
        "displayName": "Chorizo, caper & rocket pizza",
        "images": [
          {
            "url": "https://www.bbcgoodfood.com/sites/default/files/styles/recipe/public/recipe_images/recipe-image-legacy-id--690472_11.jpg",
            "responsive": {
              "url": "https://whisk-res.cloudinary.com/image/upload/v1523013475/recipe/150a727245ce61a1844d1039820286bb.jpg",
              "width": 500,
              "height": 454
            }
          }
        ],
        "tag": {
          "name": "easyDinners",
          "displayName": "Easy Dinner",
          "image": {
            "url": "https://whisk-res.cloudinary.com/image/upload/v1523894700/custom_upload/ba4d7363cd46c736675d2cc08754f5bc.png",
            "width": 800,
            "height": 800
          }
        }
      },
      "content": {
        "id": "9847a3d1ca5d11e7ae7e42010a9a0035",
        "name": "Chorizo, caper & rocket pizza",
        "description": "Capers, rocket and chorizo give this quick pizza a punchy flavour",
        "author": {
          "name": "Good Food"
        },
        "images": [
          {
            "url": "https://www.bbcgoodfood.com/sites/default/files/styles/recipe/public/recipe_images/recipe-image-legacy-id--690472_11.jpg",
            "responsive": {
              "url": "https://whisk-res.cloudinary.com/image/upload/v1523013475/recipe/150a727245ce61a1844d1039820286bb.jpg",
              "width": 500,
              "height": 454
            }
          }
        ],
        "source": {
          "name": "bbcgoodfood.com",
          "displayName": "BBC Good Food",
          "sourceRecipeUrl": "https://www.bbcgoodfood.com/recipes/1506638/chorizo-caper-and-rocket-pizza",
          "license": "Fairuse",
          "image": {
            "url": "https://whisk-res.cloudinary.com/image/upload/publishers/logos/bbcgoodfood-logo.png",
            "responsive": {
              "url": "https://whisk-res.cloudinary.com/image/upload/publishers/logos/bbcgoodfood-logo.png",
              "width": 256,
              "height": 256
            }
          }
        }
      }
    }
  ],
  "paging": {
    "cursors": {
      "after": "eyJwYWdlSWQiOiJiNjY4YWJmYy0xNzMzLTQ0MjQtYjBjMS03ZjJlMzIxNjU4YTgiLCJwcmV2aW91c0lkIjoiMjEwNzBlNTYtNDQ5Yy00Nzc5LTg0NjgtOTJjNzM3YzkxNDMxIiwibmV4dElkIjpudWxsfQ=="
    }
  }
}
```