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.

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.

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

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

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

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

PreviousRecipe Discovery NextRecipe Search

Last updated 4 years ago

Pagination

Personalization

Feed content

Tags

Feed groups

Example of feed group usage:

Parameters

FeedResponse

FeedElement

Paging

Cursors

FeedItemKey

FeedItemDisplay

FeedItemTag

FeedGroupContent

FeedLinkContent

FeedRecipeContent

ImageContainer

VideoContainer

RecipeSource

ResponsiveImage

RecipeAuthor

RecipeSaved

Sample Request

Sample Response