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.

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 is used, user properties will be considered in resulting feed e.g diets and 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 recipebut you can specify other types in parameter allowedTypes.

Tags

Feed items can be marked with tag:

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

{
  "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 filterKeyin feed query param alongside feed id.

Example:

filterKey=category::bbq-and-grilling

(filterKey should be extracted from group filterKeyfield)

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:

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 filterKeyfrom group FeedElement into filterKeyparameter of a feed request.

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

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

Sample Response

{
  "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=="
    }
  }
}