# 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](/master/guides/quick-start-guide.md) and at the [Showcase](https://showcase.whisk.com/recipes/search).

## Filter Operators

Only a `nutrition`filter 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:

```bash
nutrition=energy>200,energy<500
```

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

## User preferences

You can specify [userId](/master/api/user-model.md#model) to get the personalized result of the search. Whisk considers User Preferences such as [diets](/master/resources/recipe-labels.md#diets), [avoidances](/master/resources/recipe-labels.md#avoidances) and `dislikedIngredients`in 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

```bash
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

```javascript
{
  "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
  }
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.whisk.com/master/api/recipe-discovery/recipe-search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.