Get Feed

GET
/v1beta/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 unique id which you can find in respose. 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 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.).

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

Personalisation

If userId was specified, 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 userId was specified. Or you can force country in feed request parameters.

Feed content

We provide different types of feed content. By default it is only recipe but you can specify other types in parameterallowedTypes

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

Feed can include groups which 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 specific group you need to provide filterKey in feed query param alongside feed id. Example: 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:

curl "https://graph.whisk.com/v1beta/feed?limit=5&allowedContent=recipe,group" \ -H "Accept: application/json" \ -H "Authorization: Token <Access-Token>"
Step 2: If user clicks on one of group items in the feed, you can get specific feed for items related to this group. All you need it is pass field filterKey from group FeedElement into filterKey parameter of feed request.
curl "https://graph.whisk.com/v1beta/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 a size of the feed and rotate items using provided cursors in required timing.

Parameters

ATTRIBUTETYPEDESCRIPTION
limitinteger

This is the maximum number of objects that may be returned

Default value: 16
beforestring

This is the cursor to return data on a page before it.

afterstring

This is the cursor to return data from a next page.

idstring

Feed identifier

userIdstring

Whisk user identifier, allows considering user settings (e.g. diets and allergies) in feed result.

countrystring

Country in ISO 3166-1 alpha-2 format e.g. GB, US, ...

Default value: GB
languagestring

Language in ISO 639-1 format e.g. en, it, de ...

Default value: en
allowedContentarray

List of feed types

Possible values: recipe, link, group.
Default value: recipe
labelsarray [string]
excludeIngredientsarray [string]

recipes should not have any of these ingredients

filterKeystring

Filter by a group allows to get items related to specific group. Example: category::quick-and-easy

tagsarray

List of feed recommendation tags

Possible values: easyDinners, dinners, trending, healthy.
fieldsarray [string]

Extra fields to return on recipe

Sample Request

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

FeedResponse

ATTRIBUTETYPEDESCRIPTION
id*string

Unique feed identifier

feed*array [FeedElement]
paging*Paging

FeedElement

Element of the Feed

ATTRIBUTETYPEDESCRIPTION
type*string

type of feed element

key*FeedItemKey

key to identify Feed element. Used when submit feed impressions

displayFeedItemDisplay

contains generic information related to displaying FeedElement

content*one of
Discriminator field: type
filterKeystring

key to fetch content inside group. see filterKey feed query parameter

Paging

ATTRIBUTETYPEDESCRIPTION
cursors*Cursors

Cursors

ATTRIBUTETYPEDESCRIPTION
afterstring
beforestring

FeedItemKey

ATTRIBUTETYPEDESCRIPTION
id*string

Unique feed element identifier

FeedItemDisplay

Sufficient information to display feed item.
ATTRIBUTETYPEDESCRIPTION
displayName*string
images*array [string]
tagFeedItemTag

FeedItemTag

ATTRIBUTETYPEDESCRIPTION
name*array
Possible values: easyDinners, dinners, trending, healthy.
displayNamestring

readable name

imageResponsiveImage

FeedGroupContent

ATTRIBUTETYPEDESCRIPTION
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

ATTRIBUTETYPEDESCRIPTION
id*string

unique link identifier

displayText*string

link text

url*string

link URL

FeedRecipeContent

ATTRIBUTETYPEDESCRIPTION
id*string
name*string
descriptionstring
authorRecipeAuthor
imagesarray [ImageContainer]
videosarray [VideoContainer]
source*RecipeSource
savedRecipeSaved

This field is populated if fields=saved is added to request parameters

ImageContainer

ATTRIBUTETYPEDESCRIPTION
url*string
responsiveImageResponsiveImage

VideoContainer

ATTRIBUTETYPEDESCRIPTION
urlstring

URL to original video provider page

contentUrlstring

URL to video file. Actual bytes of the media object

embedUrlstring

An embed format of video with player

playerTypeenum
Possible values: flash, html5, silverlight.
thumbnailstring

A thumbnail image relevant to the Video

durationnumber

The duration of the recording

heightnumber

The height of the item

widthnumber

The width of the item

RecipeSource

ATTRIBUTETYPEDESCRIPTION
name*string
displayNamestring
sourceRecipeUrlstring
licensestring
imageImageContainer

ResponsiveImage

ATTRIBUTETYPEDESCRIPTION
url*string

Hosted url of an image

width*integer

Image width

height*integer

Image height

RecipeAuthor

ATTRIBUTETYPEDESCRIPTION
name*string
imageImageContainer

RecipeSaved

ATTRIBUTETYPEDESCRIPTION
valueboolean

True if this recipe is saved to favorites

collectionIdsarray [string]

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://my.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==" } } }