Recipe Search

GET	/v1/search?type=recipe

Recipe search can be performed through generic Graph API search endpoint by passing type=recipe. You can see an example of using this API at Getting Started and at the Showcase.

Filter Operators

Only a nutritionfilter accepts filter operators at the moment.

OPERATOR	DESCRIPTION	URL ENCODED FORM	EXAMPLES
>	Greater than	%3E	Return results where recipe energy greater than 100 kcal: nutrition=energy>100
<	Less than	%3C	Return results where a recipe fat less than 20 g: nutrition=fat
>=	Greater than or equal to	%3E%3D	Return results where a recipe carbohydrate is 5 g or more: nutrition=carbohydrate>=5

Parameters can be combined. This example returns recipe with energy between 200 and 500 kcal:

nutrition=energy>200,energy<500

Available nutrients for filtering: energy, fat, carbohydrate, protein

User preferences

You can specify userId to get the personalized result of the search. Whisk considers User Preferences such as diets, avoidances and dislikedIngredientsin recipe search.

Query parameters have more priority than user preferences. It means that, if a user diet is vegan and you pass in parametersdiets=pescatarian, a response will be recipes which support pescatarian diet

Parameters

ATTRIBUTE	TYPE	DESCRIPTION
q	string	Search phrase
limit	integer	This is the maximum number of objects that may be returned per page. Default: 25 Maximum: 500
before	string	This is the cursor to return data on a page before it.
after	string	This is the cursor to return data on a page before it.
labels	array [string]	how to use labels
nutrition	array [string]	nutrition filters e.g. energy>300, energy
minHealthScore	double	filter recipes with healthScore more than specified value
category	string	recipe category depends on a language available categories
excludeIngredients	array [string]	recipes should not have any of these ingredients
includeIngredients	string	Recipes should include this ingredient.
minIngredientsShouldMatch	int	if includeIngredients specified, number of minimum ingredients, which should be matched
maxTimeInMinutes	int	recipes should take this total time at maximum
country	string	Recipes should be from this country. Defaults to 'GB'.
language	string	recipes should be in this language, it allows only ISO 639-1 language codes Default value: en
userId	string	Identifier of a user in Whisk system, more about user

Response

Recipe search response with paging

ATTRIBUTE	TYPE	DESCRIPTION
data*	array [RecipeSearchHit]
paging*	FinitePaging

RecipeSearchHit

Recipe content and search metadata

ATTRIBUTE	TYPE	DESCRIPTION
content*	RecipeResponse
matchedIngredients	MatchedIngredient

MatchedIngredient

Ingredients from request parameter includeIngredients which was matched

ATTRIBUTE	TYPE	DESCRIPTION
name	string	Requested ingredient

RecipeResponse

ATTRIBUTE	TYPE	DESCRIPTION
id*	string
name*	string
description	string
numberOfServings	number	Original number of servings
numberOfServingsScaled	number	Requested number of servings
normalizedIngredients*	array [NormalizedIngredient]
ingredients	array [RawIngredient]
instructions	RecipeInstructions
images	array [ImageContainer]
videos	array [VideoContainer]
source*	RecipeSource
durations	RecipeDurations
labels*	RecipeLabels
nutrition	RecipeNutrition
constraints	RecipeConstraints
saved	RecipeSaved	This field is populated if fields=saved is added to request parameters
author	RecipeAuthor

NormalizedIngredient

ATTRIBUTE	TYPE	DESCRIPTION
text*	string
group	string
analysis	RecipeIngredientAnalysis

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

RecipeLabels

ATTRIBUTE	TYPE	DESCRIPTION
mealType*	array [RecipeLabel]
cuisine*	array [RecipeLabel]
category*	array [RecipeLabel]

RecipeLabel

ATTRIBUTE	TYPE	DESCRIPTION
name*	string
displayName*	string

RecipeDurationsResponse

ATTRIBUTE	TYPE	DESCRIPTION
cookTime	number	Cooking time in minutes
prepTime	number	Preparation time in minutes
totalTime	number	Total time in minutes

FinitePaging

ATTRIBUTE	TYPE	DESCRIPTION
cursors*	Cursors
total*	integer

Cursors

ATTRIBUTE	TYPE	DESCRIPTION
after	string
before	string

RecipeIngredientAnalysis

ATTRIBUTE	TYPE	DESCRIPTION
product*	string
canonicalName*	string
quantity	number
unit	string
multiplier	number
brand	string
comment	string
category	string

RecipeInstruction

ATTRIBUTE	TYPE	DESCRIPTION
text*	string
group	string
images	array [ImageContainer]

RecipeInstructions

ATTRIBUTE	TYPE	DESCRIPTION
steps*	array [RecipeInstruction]

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.

RecipeAuthor

ATTRIBUTE	TYPE	DESCRIPTION
name*	string
image	ImageContainer

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

ResponsiveImage

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

Sample Request

curl "https://graph.whisk.com/v1/search?q=sandwich&type=recipe&includeIngredients=bread,meat" \
    -H "Accept: application/json" \
    -H "Authorization: Token <Access-Token>"

Sample Response

{
  "data": [
    {
      "content": {
        "id": "97f77cceca5d11e7ae7e42010a9a0035",
        "name": "Quick coronation chicken sandwich",
        "description": "Use leftover roast chicken to make a delicious coronation chicken sandwich ready to pack in your lunchbox.",
        "images": [
          {
            "url": "http://cdnwp.audiencemedia.com/wp-content/uploads/2015/01/478091-1-eng-GB_coronation-chick-sandwich-470x540.jpg",
            "responsive": {
              "url": "https://lh3.googleusercontent.com/crjY_vyxK8kdBYYBd6VVtlGwIXuG3pn9DuCSWP4-_VtURbrYfpKPrYDMmrlCwc8kqSAsgCBtjhqU2C7PEjU0wMDh4FSK",
              "width": 470,
              "height": 540
            }
          },
          {
            "url": "http://cdnwp.audiencemedia.com/wp-content/uploads/2015/01/478091-1-eng-GB_coronation-chick-sandwich.jpg",
            "responsive": {
              "url": "https://lh3.googleusercontent.com/fz02xdShfu1ax6ZZLhMp2zn7WwGXN7XlVx6ZXR8X_uN-x5DEdCW_Q9tIacitVtyI-yIkxZ6-nqpLCQIrPNijwM4wIPg",
              "width": 960,
              "height": 927
            }
          }
        ],
        "source": {
          "name": "deliciousmagazine.co.uk",
          "displayName": "delicious. magazine",
          "sourceRecipeUrl": "http://www.deliciousmagazine.co.uk/recipes/quick-coronation-chicken-sandwich/",
          "license": "Fairuse",
          "image": {
            "url": "https://res.cloudinary.com/whisk/image/upload/v1401879186/content/publisher_logos/delicious-magazine-logo.png",
            "responsive": {
              "url": "https://res.cloudinary.com/whisk/image/upload/v1401879186/content/publisher_logos/delicious-magazine-logo.png",
              "width": 200,
              "height": 200
            }
          }
        },
        "author": {
          "name": "Author name",
          "image": {
            "url": "https://whisk-res.cloudinary.com/image/upload/v1523894700/custom_upload/ba4d7363cd46c736675d2cc08754f5bc.png",
            "responsive": {
              "url": "https://whisk-res.cloudinary.com/image/upload/v1523894700/custom_upload/ba4d7363cd46c736675d2cc08754f5bc.png",
              "width": 800,
              "height": 800
            }
          }
        },
        "numberOfServings": 1,
        "labels": {
          "mealType": [],
          "cuisine": [],
          "category": [
            {
              "name": "quick-and-easy",
              "displayName": "Quick and easy"
            }
          ]
        }
      },
      "matchedIngredients": [
        {
          "name": "meat"
        },
        {
          "name": "bread"
        }
      ]
    },
    {
      "content": {
        "id": "99a8776cca5d11e7ae7e42010a9a0035",
        "name": "Club sandwich",
        "description": "This layered sandwich, a favourite of gastro-pubs across the country, makes a tasty meal for one",
        "images": [
          {
            "url": "https://www.bbcgoodfood.com/sites/default/files/styles/recipe/public/recipe_images/recipe-image-legacy-id--653594_11.jpg",
            "responsive": {
              "url": "https://lh3.googleusercontent.com/ZMk_3U8-5UbbwTFxXhHxuorv1KGB5ll5HG--2Ru1UuAZ9-uFOrNa_fNq5CfyssAAJbUKy8Rpno_-kpi3F_VZI721w6Q",
              "width": 500,
              "height": 454
            }
          }
        ],
        "source": {
          "name": "bbcgoodfood.com",
          "displayName": "BBC Good Food",
          "sourceRecipeUrl": "https://www.bbcgoodfood.com/recipes/1363639/club-sandwich",
          "license": "Fairuse",
          "image": {
            "url": "https://res.cloudinary.com/whisk/image/upload/v1401879186/content/publisher_logos/foodnetwork-logo.png",
            "responsive": {
              "url": "https://res.cloudinary.com/whisk/image/upload/v1401879186/content/publisher_logos/foodnetwork-logo.png",
              "width": 200,
              "height": 200
            }
          }
        },
        "author": {
          "name": "Author name",
          "image": {
            "url": "https://whisk-res.cloudinary.com/image/upload/v1523894700/custom_upload/ba4d7363cd46c736675d2cc08754f5bc.png",
            "responsive": {
              "url": "https://whisk-res.cloudinary.com/image/upload/v1523894700/custom_upload/ba4d7363cd46c736675d2cc08754f5bc.png",
              "width": 800,
              "height": 800
            }
          }
        },
        "numberOfServings": 1,
        "durations": {
          "cookTime": 10,
          "prepTime": 10,
          "totalTime": 20
        },
        "labels": {
          "mealType": [],
          "cuisine": [
            {
              "name": "british",
              "displayName": "British"
            }
          ],
          "category": [
            {
              "name": "dinner",
              "displayName": "Dinner"
            },
            {
              "name": "quick-and-easy",
              "displayName": "Quick and easy"
            },
            {
              "name": "appetizers-and-snacks",
              "displayName": "Appetizers and Snacks"
            },
            {
              "name": "lunch",
              "displayName": "Lunch"
            },
            {
              "name": "main-dishes",
              "displayName": "Main Dishes"
            }
          ]
        }
      },
      "matchedIngredients": [
        {
          "name": "bread"
        },
        {
          "name": "meat"
        }
      ]
    }
  ],
  "paging": {
    "cursors": {
      "after": "eyJpZCI6ImNhZjVlOWY3Y2YxNzFkYjBmZTdkYjJmOTM4M2M0ZDIzIiwiaW5kZXgiOjF9"
    },
    "total": 1300
  }