Documentation

Search Recipes by Ingredients

Ever wondered what recipes you can cook with the ingredients you have in your fridge or pantry? This endpoint lets you find recipes that either maximize the usage of ingredients you have at hand (pre shopping) or minimize the ingredients that you don't currently have (post shopping).

Find recipes that use as many of the given ingredients as possible and require as few additional ingredients as possible. This is a "what's in your fridge" API endpoint.

Headers

Response Headers:

• Content-Type: application/json

Parameters

[
    {
        "id": 73420,
        "image": "https://img.spoonacular.com/recipes/73420-312x231.jpg",
        "imageType": "jpg",
        "likes": 0,
        "missedIngredientCount": 3,
        "missedIngredients": [
            {
                "aisle": "Baking",
                "amount": 1.0,
                "id": 18371,
                "image": "https://img.spoonacular.com/ingredients_100x100/white-powder.jpg",
                "meta": [],
                "name": "baking powder",
                "original": "1 tsp baking powder",
                "originalName": "baking powder",
                "unit": "tsp",
                "unitLong": "teaspoon",
                "unitShort": "tsp"
            },
            {
                "aisle": "Spices and Seasonings",
                "amount": 1.0,
                "id": 2010,
                "image": "https://img.spoonacular.com/ingredients_100x100/cinnamon.jpg",
                "meta": [],
                "name": "cinnamon",
                "original": "1 tsp cinnamon",
                "originalName": "cinnamon",
                "unit": "tsp",
                "unitLong": "teaspoon",
                "unitShort": "tsp"
            },
            {
                "aisle": "Milk, Eggs, Other Dairy",
                "amount": 1.0,
                "id": 1123,
                "image": "https://img.spoonacular.com/ingredients_100x100/egg.png",
                "meta": [],
                "name": "egg",
                "original": "1 egg",
                "originalName": "egg",
                "unit": "",
                "unitLong": "",
                "unitShort": ""
            }
        ],
        "title": "Apple Or Peach Strudel",
        "unusedIngredients": [],
        "usedIngredientCount": 1,
        "usedIngredients": [
            {
                "aisle": "Produce",
                "amount": 6.0,
                "id": 9003,
                "image": "https://img.spoonacular.com/ingredients_100x100/apple.jpg",
                "meta": [],
                "name": "apples",
                "original": "6 large baking apples",
                "originalName": "baking apples",
                "unit": "large",
                "unitLong": "larges",
                "unitShort": "large"
            }
        ]
    },
    {
        "id": 632660,
        "image": "https://img.spoonacular.com/recipes/632660-312x231.jpg",
        "imageType": "jpg",
        "likes": 3,
        "missedIngredientCount": 4,
        "missedIngredients": [
            {
                "aisle": "Milk, Eggs, Other Dairy",
                "amount": 1.5,
                "extendedName": "unsalted butter",
                "id": 1001,
                "image": "https://img.spoonacular.com/ingredients_100x100/butter-sliced.jpg",
                "meta": [
                    "unsalted",
                    "cold"
                ],
                "name": "butter",
                "original": "1 1/2 sticks cold unsalted butter cold unsalted butter<",
                "originalName": "cold unsalted butter cold unsalted butter<",
                "unit": "sticks",
                "unitLong": "sticks",
                "unitShort": "sticks"
            },
            {
                "aisle": "Produce",
                "amount": 4.0,
                "id": 1079003,
                "image": "https://img.spoonacular.com/ingredients_100x100/red-delicious-apples.png",
                "meta": [
                    "red",
                    " such as golden delicious, peeled, cored and cut into 1/4-inch-thick slices "
                ],
                "name": "red apples",
                "original": "4 larges red apples, such as Golden Delicious, peeled, cored and cut into 1/4-inch-thick slices",
                "originalName": "s red apples, such as Golden Delicious, peeled, cored and cut into 1/4-inch-thick slices",
                "unit": "large",
                "unitLong": "larges",
                "unitShort": "large"
            },
            {
                "aisle": "Spices and Seasonings",
                "amount": 2.0,
                "id": 2010,
                "image": "https://img.spoonacular.com/ingredients_100x100/cinnamon.jpg",
                "meta": [],
                "name": "cinnamon",
                "original": "2 teaspoons cinnamon",
                "originalName": "cinnamon",
                "unit": "teaspoons",
                "unitLong": "teaspoons",
                "unitShort": "tsp"
            },
            {
                "aisle": "Nut butters, Jams, and Honey",
                "amount": 2.0,
                "id": 19719,
                "image": "https://img.spoonacular.com/ingredients_100x100/apricot-jam.jpg",
                "meta": [
                    "melted"
                ],
                "name": "apricot preserves",
                "original": "2 tablespoons apricot preserves, melted and strained",
                "originalName": "apricot preserves, melted and strained",
                "unit": "tablespoons",
                "unitLong": "tablespoons",
                "unitShort": "Tbsp"
            }
        ],
        "title": "Apricot Glazed Apple Tart",
        "unusedIngredients": [
            {
                "aisle": "Produce",
                "amount": 1.0,
                "id": 9003,
                "image": "https://img.spoonacular.com/ingredients_100x100/apple.jpg",
                "meta": [],
                "name": "apples",
                "original": "apples",
                "originalName": "apples",
                "unit": "serving",
                "unitLong": "serving",
                "unitShort": "serving"
            }
        ],
        "usedIngredientCount": 0,
        "usedIngredients": []
    }
]

If you need more filter options, consider using the recipe search and set the sort parameter to max-used-ingredients or min-missing-ingredients.

The API response will give you arrays of usedIngredients, missedIngredients, and unusedIngredients for each returned recipe. This diagram shows you what they mean:

Quotas

Search Recipes by Nutrients

Find a set of recipes that adhere to the given nutritional limits. You may set limits for macronutrients (calories, protein, fat, and carbohydrate) and/or many micronutrients.

Headers

Response Headers:

• Content-Type: application/json

Parameters

[
    {
        "calories": 210,
        "carbs": "43g",
        "fat": "3g",
        "id": 90629,
        "image": "https://img.spoonacular.com/recipes/90629-312x231.jpg",
        "imageType": "jpg",
        "protein": "1g",
        "title": "Baked Apples in White Wine"
    },
    {
        "calories": 226,
        "carbs": "33g",
        "fat": "10g",
        "id": 284420,
        "image": "https://img.spoonacular.com/recipes/284420-312x231.jpg",
        "imageType": "jpg",
        "protein": "2g",
        "title": "Chocolate Silk Pie with Marshmallow Meringue"
    }
]

Quotas

Search Recipes

Search through thousands of recipes using advanced filtering and ranking. NOTE: This method combines searching by query, by ingredients, and by nutrients into one endpoint.

If you are making a "what's in your fridge?" style app and require more filters than the Search Recipes by Ingredients endpoint allows, use the sort parameters max-used-ingredients or min-missing-ingredients with this endpoint instead.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "offset": 0,
    "number": 2,
    "results": [
        {
            "id": 716429,
            "title": "Pasta with Garlic, Scallions, Cauliflower & Breadcrumbs",
            "image": "https://img.spoonacular.com/recipes/716429-312x231.jpg",
            "imageType": "jpg",
        },
        {
            "id": 715538,
            "title": "What to make for dinner tonight?? Bruschetta Style Pork & Pasta",
            "image": "https://img.spoonacular.com/recipes/715538-312x231.jpg",
            "imageType": "jpg",
        }
    ],
    "totalResults": 86
}

The API response will give you arrays of usedIngredients, missedIngredients, and unusedIngredients for each returned recipe. This diagram shows you what they mean:

Quotas

Get Recipe Information

Use a recipe id to get full information about a recipe, such as ingredients, nutrition, diet and allergen information, etc.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "id": 716429,
    "title": "Pasta with Garlic, Scallions, Cauliflower & Breadcrumbs",
    "image": "https://img.spoonacular.com/recipes/716429-556x370.jpg",
    "imageType": "jpg",
    "servings": 2,
    "readyInMinutes": 45,
    "license": "CC BY-SA 3.0",
    "sourceName": "Full Belly Sisters",
    "sourceUrl": "http://fullbellysisters.blogspot.com/2012/06/pasta-with-garlic-scallions-cauliflower.html",
    "spoonacularSourceUrl": "https://spoonacular.com/pasta-with-garlic-scallions-cauliflower-breadcrumbs-716429",
    "healthScore": 19.0,
    "spoonacularScore": 83.0,
    "pricePerServing": 163.15,
    "analyzedInstructions": [],
    "cheap": false,
    "creditsText": "Full Belly Sisters",
    "cuisines": [],
    "dairyFree": false,
    "diets": [],
    "gaps": "no",
    "glutenFree": false,
    "instructions": "",
    "ketogenic": false,
    "lowFodmap": false,
    "occasions": [],
    "sustainable": false,
    "vegan": false,
    "vegetarian": false,
    "veryHealthy": false,
    "veryPopular": false,
    "whole30": false,
    "weightWatcherSmartPoints": 17,
    "dishTypes": [
        "lunch",
        "main course",
        "main dish",
        "dinner"
    ],
    "extendedIngredients": [
        {
            "aisle": "Milk, Eggs, Other Dairy",
            "amount": 1.0,
            "consitency": "solid",
            "id": 1001,
            "image": "butter-sliced.jpg",
            "measures": {
                "metric": {
                    "amount": 1.0,
                    "unitLong": "Tbsp",
                    "unitShort": "Tbsp"
                },
                "us": {
                    "amount": 1.0,
                    "unitLong": "Tbsp",
                    "unitShort": "Tbsp"
                }
            },
            "meta": [],
            "name": "butter",
            "original": "1 tbsp butter",
            "originalName": "butter",
            "unit": "tbsp"
        },
        {
            "aisle": "Produce",
            "amount": 2.0,
            "consitency": "solid",
            "id": 10011135,
            "image": "cauliflower.jpg",
            "measures": {
                "metric": {
                    "amount": 473.176,
                    "unitLong": "milliliters",
                    "unitShort": "ml"
                },
                "us": {
                    "amount": 2.0,
                    "unitLong": "cups",
                    "unitShort": "cups"
                }
            },
            "meta": [
                "frozen",
                "thawed",
                "cut into bite-sized pieces"
            ],
            "name": "cauliflower florets",
            "original": "about 2 cups frozen cauliflower florets, thawed, cut into bite-sized pieces",
            "originalName": "about frozen cauliflower florets, thawed, cut into bite-sized pieces",
            "unit": "cups"
        },
        {
            "aisle": "Cheese",
            "amount": 2.0,
            "consitency": "solid",
            "id": 1041009,
            "image": "cheddar-cheese.png",
            "measures": {
                "metric": {
                    "amount": 2.0,
                    "unitLong": "Tbsps",
                    "unitShort": "Tbsps"
                },
                "us": {
                    "amount": 2.0,
                    "unitLong": "Tbsps",
                    "unitShort": "Tbsps"
                }
            },
            "meta": [
                "grated",
                "(I used romano)"
            ],
            "name": "cheese",
            "original": "2 tbsp grated cheese (I used romano)",
            "originalName": "grated cheese (I used romano)",
            "unit": "tbsp"
        },
        {
            "aisle": "Oil, Vinegar, Salad Dressing",
            "amount": 1.0,
            "consitency": "liquid",
            "id": 1034053,
            "image": "olive-oil.jpg",
            "measures": {
                "metric": {
                    "amount": 1.0,
                    "unitLong": "Tbsp",
                    "unitShort": "Tbsp"
                },
                "us": {
                    "amount": 1.0,
                    "unitLong": "Tbsp",
                    "unitShort": "Tbsp"
                }
            },
            "meta": [],
            "name": "extra virgin olive oil",
            "original": "1-2 tbsp extra virgin olive oil",
            "originalName": "extra virgin olive oil",
            "unit": "tbsp"
        },
        {
            "aisle": "Produce",
            "amount": 5.0,
            "consitency": "solid",
            "id": 11215,
            "image": "garlic.jpg",
            "measures": {
                "metric": {
                    "amount": 5.0,
                    "unitLong": "cloves",
                    "unitShort": "cloves"
                },
                "us": {
                    "amount": 5.0,
                    "unitLong": "cloves",
                    "unitShort": "cloves"
                }
            },
            "meta": [],
            "name": "garlic",
            "original": "5-6 cloves garlic",
            "originalName": "garlic",
            "unit": "cloves"
        },
        {
            "aisle": "Pasta and Rice",
            "amount": 6.0,
            "consitency": "solid",
            "id": 20420,
            "image": "fusilli.jpg",
            "measures": {
                "metric": {
                    "amount": 170.097,
                    "unitLong": "grams",
                    "unitShort": "g"
                },
                "us": {
                    "amount": 6.0,
                    "unitLong": "ounces",
                    "unitShort": "oz"
                }
            },
            "meta": [
                "(I used linguine)"
            ],
            "name": "pasta",
            "original": "6-8 ounces pasta (I used linguine)",
            "originalName": "pasta (I used linguine)",
            "unit": "ounces"
        },
        {
            "aisle": "Spices and Seasonings",
            "amount": 2.0,
            "consitency": "solid",
            "id": 1032009,
            "image": "red-pepper-flakes.jpg",
            "measures": {
                "metric": {
                    "amount": 2.0,
                    "unitLong": "pinches",
                    "unitShort": "pinches"
                },
                "us": {
                    "amount": 2.0,
                    "unitLong": "pinches",
                    "unitShort": "pinches"
                }
            },
            "meta": [
                "red"
            ],
            "name": "red pepper flakes",
            "original": "couple of pinches red pepper flakes, optional",
            "originalName": "couple of red pepper flakes, optional",
            "unit": "pinches"
        },
        {
            "aisle": "Spices and Seasonings",
            "amount": 2.0,
            "consitency": "solid",
            "id": 1102047,
            "image": "salt-and-pepper.jpg",
            "measures": {
                "metric": {
                    "amount": 2.0,
                    "unitLong": "servings",
                    "unitShort": "servings"
                },
                "us": {
                    "amount": 2.0,
                    "unitLong": "servings",
                    "unitShort": "servings"
                }
            },
            "meta": [
                "to taste"
            ],
            "name": "salt and pepper",
            "original": "salt and pepper, to taste",
            "originalName": "salt and pepper, to taste",
            "unit": "servings"
        },
        {
            "aisle": "Produce",
            "amount": 3.0,
            "consitency": "solid",
            "id": 11291,
            "image": "spring-onions.jpg",
            "measures": {
                "metric": {
                    "amount": 3.0,
                    "unitLong": "",
                    "unitShort": ""
                },
                "us": {
                    "amount": 3.0,
                    "unitLong": "",
                    "unitShort": ""
                }
            },
            "meta": [
                "white",
                "green",
                "separated",
                "chopped"
            ],
            "name": "scallions",
            "original": "3 scallions, chopped, white and green parts separated",
            "originalName": "scallions, chopped, white and green parts separated",
            "unit": ""
        },
        {
            "aisle": "Alcoholic Beverages",
            "amount": 2.0,
            "consitency": "liquid",
            "id": 14106,
            "image": "white-wine.jpg",
            "measures": {
                "metric": {
                    "amount": 2.0,
                    "unitLong": "Tbsps",
                    "unitShort": "Tbsps"
                },
                "us": {
                    "amount": 2.0,
                    "unitLong": "Tbsps",
                    "unitShort": "Tbsps"
                }
            },
            "meta": [
                "white"
            ],
            "name": "white wine",
            "original": "2-3 tbsp white wine",
            "originalName": "white wine",
            "unit": "tbsp"
        },
        {
            "aisle": "Pasta and Rice",
            "amount": 0.25,
            "consitency": "solid",
            "id": 99025,
            "image": "breadcrumbs.jpg",
            "measures": {
                "metric": {
                    "amount": 59.147,
                    "unitLong": "milliliters",
                    "unitShort": "ml"
                },
                "us": {
                    "amount": 0.25,
                    "unitLong": "cups",
                    "unitShort": "cups"
                }
            },
            "meta": [
                "whole wheat",
                "(I used panko)"
            ],
            "name": "whole wheat bread crumbs",
            "original": "1/4 cup whole wheat bread crumbs (I used panko)",
            "originalName": "whole wheat bread crumbs (I used panko)",
            "unit": "cup"
        }
    ],
    "summary": "Pasta with Garlic, Scallions, Cauliflower & Breadcrumbs might be a good recipe to expand your main course repertoire. One portion of this dish contains approximately <b>19g of protein </b>,  <b>20g of fat </b>, and a total of  <b>584 calories </b>. For  <b>$1.63 per serving </b>, this recipe  <b>covers 23% </b> of your daily requirements of vitamins and minerals. This recipe serves 2. It is brought to you by fullbellysisters.blogspot.com. 209 people were glad they tried this recipe. A mixture of scallions, salt and pepper, white wine, and a handful of other ingredients are all it takes to make this recipe so scrumptious. From preparation to the plate, this recipe takes approximately  <b>45 minutes </b>. All things considered, we decided this recipe  <b>deserves a spoonacular score of 83% </b>. This score is awesome. If you like this recipe, take a look at these similar recipes: <a href=\"https://spoonacular.com/recipes/cauliflower-gratin-with-garlic-breadcrumbs-318375\">Cauliflower Gratin with Garlic Breadcrumbs</a>, < href=\"https://spoonacular.com/recipes/pasta-with-cauliflower-sausage-breadcrumbs-30437\">Pasta With Cauliflower, Sausage, & Breadcrumbs</a>, and <a href=\"https://spoonacular.com/recipes/pasta-with-roasted-cauliflower-parsley-and-breadcrumbs-30738\">Pasta With Roasted Cauliflower, Parsley, And Breadcrumbs</a>.",
    "winePairing": {
        "pairedWines": [
            "chardonnay",
            "gruener veltliner",
            "sauvignon blanc"
        ],
        "pairingText": "Chardonnay, Gruener Veltliner, and Sauvignon Blanc are great choices for Pasta. Sauvignon Blanc and Gruner Veltliner both have herby notes that complement salads with enough acid to match tart vinaigrettes, while a Chardonnay can be a good pick for creamy salad dressings. The Buddha Kat Winery Chardonnay with a 4 out of 5 star rating seems like a good match. It costs about 25 dollars per bottle.",
        "productMatches": [
            {
                "id": 469199,
                "title": "Buddha Kat Winery Chardonnay",
                "description": "We barrel ferment our Chardonnay and age it in a mix of Oak and Stainless. Giving this light bodied wine modest oak character, a delicate floral aroma, and a warming finish.",
                "price": "$25.0",
                "imageUrl": "https://img.spoonacular.com/products/469199-312x231.jpg",
                "averageRating": 0.8,
                "ratingCount": 1.0,
                "score": 0.55,
                "link": "https://www.amazon.com/2015-Buddha-Kat-Winery-Chardonnay/dp/B00OSAVVM4?tag=spoonacular-20"
            }
        ]
    }
}

Quotas

Get Recipe Information Bulk

Get information about multiple recipes at once. This is equivalent to calling the Get Recipe Information endpoint multiple times, but faster.

Headers

Response Headers:

• Content-Type: application/json

Parameters

[
    {/* recipe data as in Get Recipe Information endpoint */},
    {/* recipe data as in Get Recipe Information endpoint */}
]

Quotas

Get Similar Recipes

Find recipes which are similar to the given one.

Headers

Response Headers:

• Content-Type: application/json

Parameters

[
    {
        "id": 209128,
        "title": "Dinner Tonight: Grilled Romesco-Style Pork",
        "imageType": "jpg",
        "readyInMinutes": 45,
        "servings": 4,
        "sourceUrl": "http://www.seriouseats.com/recipes/2008/07/grilled-romesco-style-pork-salad-recipe.html"
    },
    {
        "id": 31868,
        "title": "Dinner Tonight: Chickpea Bruschetta",
        "imageType": "jpg",
        "readyInMinutes": 45,
        "servings": 2,
        "sourceUrl": "http://www.seriouseats.com/recipes/2009/06/dinner-tonight-chickpea-bruschetta-babbo-nyc-recipe.html"
    }
]

Quotas

Get Random Recipes

Find random (popular) recipes. If you need to filter recipes by diet, nutrition etc. you might want to consider using the complex recipe search endpoint and set the sort request parameter to random.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "recipes":[
        {/* recipe data as in Get Recipe Information endpoint */}
    ]
}

Quotas

Autocomplete Recipe Search

Autocomplete a partial input to suggest possible recipe names.

Headers

Response Headers:

• Content-Type: application/json

Parameters

[
    {
        "id": 296687,
        "title": "chicken",
        "imageType": "jpg"
    },
    {
        "id": 42569,
        "title": "chicken bbq",
        "imageType": "jpg"
    },

    {
        "id": 83890,
        "title": "chicken blt",
        "imageType": "jpg"
    },
    {
        "id": 737543,
        "title": "chicken pie",
        "imageType": "jpg"
    }
]

Quotas

Taste by ID

Get a recipe's taste. The tastes supported are sweet, salty, sour, bitter, savory, and fatty. These tastes are between 0 and 100 while the spiciness value is in scoville on an open scale of 0 and above.

Every ingredient has each of these values and it is weighted by how much they contribute to the recipe. Spiciness is taking the weight of the spicy ingredient and multiplying it with its scoville amount. Of course, taste is also very personal and it depends on how it is prepared so all of the values should only give you an indication of how the dish tastes.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "sweetness": 28.79,
    "saltiness": 26.74,
    "sourness": 6.22,
    "bitterness": 12.38,
    "savoriness": 11.8,
    "fattiness": 100,
    "spiciness": 0
}

Quotas

Equipment by ID

Get a recipe's equipment list.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "equipment": [
        {
            "image": "pie-pan.png",
            "name": "pie form"
        },
        {
            "image": "bowl.jpg",
            "name": "bowl"
        },
        {
            "image": "oven.jpg",
            "name": "oven"
        },
        {
            "image": "pan.png",
            "name": "frying pan"
        }
    ]
}

Quotas

Price Breakdown by ID

Get a recipe's price breakdown data.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "ingredients": [
        {
            "amount": {
                "metric": {
                    "unit": "g",
                    "value": 222.0
                },
                "us": {
                    "unit": "cups",
                    "value": 1.5
                }
            },
            "image": "blueberries.jpg",
            "name": "blueberries",
            "price": 174.43
        },
        {
            "amount": {
                "metric": {
                    "unit": "",
                    "value": 1.0
                },
                "us": {
                    "unit": "",
                    "value": 1.0
                }
            },
            "image": "egg-white.jpg",
            "name": "egg white",
            "price": 18.21
        },
        {
            "amount": {
                "metric": {
                    "unit": "Tbsps",
                    "value": 2.0
                },
                "us": {
                    "unit": "Tbsps",
                    "value": 2.0
                }
            },
            "image": "flour.png",
            "name": "flour",
            "price": 2.0
        },
        {
            "amount": {
                "metric": {
                    "unit": "g",
                    "value": 150.0
                },
                "us": {
                    "unit": "cup",
                    "value": 0.75
                }
            },
            "image": "sugar-in-bowl.png",
            "name": "granulated sugar",
            "price": 20.67
        },
        {
            "amount": {
                "metric": {
                    "unit": "tsp",
                    "value": 1.0
                },
                "us": {
                    "unit": "tsp",
                    "value": 1.0
                }
            },
            "image": "lemon-juice.jpg",
            "name": "fresh lemon juice",
            "price": 3.39
        },
        {
            "amount": {
                "metric": {
                    "unit": "pinch",
                    "value": 1.0
                },
                "us": {
                    "unit": "pinch",
                    "value": 1.0
                }
            },
            "image": "ground-nutmeg.jpg",
            "name": "nutmeg",
            "price": 7.39
        },
        {
            "amount": {
                "metric": {
                    "unit": "",
                    "value": 2.0
                },
                "us": {
                    "unit": "",
                    "value": 2.0
                }
            },
            "image": "pie-crust.jpg",
            "name": "pie dough round",
            "price": 364.29
        },
        {
            "amount": {
                "metric": {
                    "unit": "Tbsps",
                    "value": 2.0
                },
                "us": {
                    "unit": "Tbsps",
                    "value": 2.0
                }
            },
            "image": "tapioca-pearls.png",
            "name": "quick cooking tapioca",
            "price": 50.89
        },
        {
            "amount": {
                "metric": {
                    "unit": "g",
                    "value": 305.0
                },
                "us": {
                    "unit": "cups",
                    "value": 2.5
                }
            },
            "image": "rhubarb.jpg",
            "name": "trimmed rhubarb",
            "price": 185.18
        },
        {
            "amount": {
                "metric": {
                    "unit": "Tbsps",
                    "value": 0.5
                },
                "us": {
                    "unit": "Tbsps",
                    "value": 0.5
                }
            },
            "image": "butter-sliced.jpg",
            "name": "unsalted butter",
            "price": 6.0
        }
    ],
    "totalCost": 832.45,
    "totalCostPerServing": 104.06
}

Quotas

Ingredients by ID

Get a recipe's ingredient list.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "ingredients": [
        {
            "amount": {
                "metric": {
                    "unit": "g",
                    "value": 222.0
                },
                "us": {
                    "unit": "cups",
                    "value": 1.5
                }
            },
            "image": "blueberries.jpg",
            "name": "blueberries"
        },
        {
            "amount": {
                "metric": {
                    "unit": "",
                    "value": 1.0
                },
                "us": {
                    "unit": "",
                    "value": 1.0
                }
            },
            "image": "egg-white.jpg",
            "name": "egg white"
        },
        {
            "amount": {
                "metric": {
                    "unit": "Tbsps",
                    "value": 2.0
                },
                "us": {
                    "unit": "Tbsps",
                    "value": 2.0
                }
            },
            "image": "flour.png",
            "name": "flour"
        },
        {
            "amount": {
                "metric": {
                    "unit": "g",
                    "value": 150.0
                },
                "us": {
                    "unit": "cup",
                    "value": 0.75
                }
            },
            "image": "sugar-in-bowl.png",
            "name": "granulated sugar"
        },
        {
            "amount": {
                "metric": {
                    "unit": "tsp",
                    "value": 1.0
                },
                "us": {
                    "unit": "tsp",
                    "value": 1.0
                }
            },
            "image": "lemon-juice.jpg",
            "name": "fresh lemon juice"
        },
        {
            "amount": {
                "metric": {
                    "unit": "pinch",
                    "value": 1.0
                },
                "us": {
                    "unit": "pinch",
                    "value": 1.0
                }
            },
            "image": "ground-nutmeg.jpg",
            "name": "nutmeg"
        },
        {
            "amount": {
                "metric": {
                    "unit": "",
                    "value": 2.0
                },
                "us": {
                    "unit": "",
                    "value": 2.0
                }
            },
            "image": "pie-crust.jpg",
            "name": "pie dough round"
        },
        {
            "amount": {
                "metric": {
                    "unit": "Tbsps",
                    "value": 2.0
                },
                "us": {
                    "unit": "Tbsps",
                    "value": 2.0
                }
            },
            "image": "tapioca-pearls.png",
            "name": "quick cooking tapioca"
        },
        {
            "amount": {
                "metric": {
                    "unit": "g",
                    "value": 305.0
                },
                "us": {
                    "unit": "cups",
                    "value": 2.5
                }
            },
            "image": "rhubarb.jpg",
            "name": "trimmed rhubarb"
        },
        {
            "amount": {
                "metric": {
                    "unit": "tsps",
                    "value": 0.333
                },
                "us": {
                    "unit": "tsps",
                    "value": 0.333
                }
            },
            "image": "salt.jpg",
            "name": "salt"
        },
        {
            "amount": {
                "metric": {
                    "unit": "Tbsps",
                    "value": 0.5
                },
                "us": {
                    "unit": "Tbsps",
                    "value": 0.5
                }
            },
            "image": "butter-sliced.jpg",
            "name": "unsalted butter"
        }
    ]
}

Quotas

Recipe Nutrition Label Widget

Get a recipe's nutrition label as an HTML widget.

Headers

Response Headers:

• Content-Type: text/html

Parameters

The response will be an HTML that may look like this:

Quotas

Product Nutrition Label Widget

Get a product's nutrition label as an HTML widget.

Headers

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The response will be an HTML widget that may look like this:

Quotas

Product Nutrition Label Image

Get a product's nutrition label as an image.

Headers

Response Headers:

• Content-Type: image/png

Parameters

The response will be an image that may look like this:

Quotas

Recipe Nutrition Label Image

Get a recipe's nutrition label as an image.

Headers

Response Headers:

• Content-Type: image/png

Parameters

The response will be an image that may look like this:

Quotas

Nutrition by ID

Get a recipe's nutrition widget data.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "nutrients": [
        {
            "name": "Calories",
            "amount": 316.49,
            "unit": "kcal",
            "percentOfDailyNeeds": 15.82
        },
        {
            "name": "Fat",
            "amount": 12.09,
            "unit": "g",
            "percentOfDailyNeeds": 18.6
        },
        {
            "name": "Saturated Fat",
            "amount": 3.98,
            "unit": "g",
            "percentOfDailyNeeds": 24.88
        },
        {
            "name": "Carbohydrates",
            "amount": 49.25,
            "unit": "g",
            "percentOfDailyNeeds": 16.42
        },
        {
            "name": "Net Carbohydrates",
            "amount": 46.76,
            "unit": "g",
            "percentOfDailyNeeds": 17.0
        },
        {
            "name": "Sugar",
            "amount": 21.98,
            "unit": "g",
            "percentOfDailyNeeds": 24.42
        },
        {
            "name": "Cholesterol",
            "amount": 1.88,
            "unit": "mg",
            "percentOfDailyNeeds": 0.63
        },
        {
            "name": "Sodium",
            "amount": 279.1,
            "unit": "mg",
            "percentOfDailyNeeds": 12.13
        },
        {
            "name": "Protein",
            "amount": 3.79,
            "unit": "g",
            "percentOfDailyNeeds": 7.57
        },
       ...
    ],
    "properties": [
        {
            "name": "Glycemic Index",
            "amount": 33.51,
            "unit": ""
        },
        {
            "name": "Glycemic Load",
            "amount": 15.63,
            "unit": ""
        },
        {
            "name": "Nutrition Score",
            "amount": 5.868695652173913,
            "unit": "%"
        }
    ],
    "flavonoids": [
        {
            "name": "Cyanidin",
            "amount": 2.35,
            "unit": "mg"
        },
        {
            "name": "Petunidin",
            "amount": 8.75,
            "unit": "mg"
        },
        {
            "name": "Delphinidin",
            "amount": 9.83,
            "unit": "mg"
        },
       ...
    ],
    "ingredients": [
        {
            "id": 9050,
            "name": "blueberries",
            "amount": 0.19,
            "unit": "cups",
            "nutrients": [
                {
                    "name": "Vitamin E",
                    "amount": 0.16,
                    "unit": "mg",
                    "percentOfDailyNeeds": 3.19
                },
                {
                    "name": "Zinc",
                    "amount": 0.04,
                    "unit": "mg",
                    "percentOfDailyNeeds": 1.96
                },
                {
                    "name": "Fat",
                    "amount": 0.09,
                    "unit": "g",
                    "percentOfDailyNeeds": 18.6
                },
                {
                    "name": "Folate",
                    "amount": 1.66,
                    "unit": "µg",
                    "percentOfDailyNeeds": 9.48
                },
                {
                    "name": "Phosphorus",
                    "amount": 3.33,
                    "unit": "mg",
                    "percentOfDailyNeeds": 4.24
                },
                {
                    "name": "Manganese",
                    "amount": 0.09,
                    "unit": "mg",
                    "percentOfDailyNeeds": 18.69
                },
                ...
        },
        ...
    ],
    "caloricBreakdown": {
        "percentProtein": 4.72,
        "percentFat": 33.9,
        "percentCarbs": 61.38
    },
    "weightPerServing": {
        "amount": 138,
        "unit": "g"
    }
}

Quotas

Get Analyzed Recipe Instructions

Get an analyzed breakdown of a recipe's instructions. Each step is enriched with the ingredients and equipment required.

Headers

Response Headers:

• Content-Type: application/json

Parameters

[
    {
        "name": "",
        "steps": [
            {
                "equipment": [
                    {
                        "id": 404784,
                        "image": "oven.jpg",
                        "name": "oven",
                        "temperature": {
                            "number": 200.0,
                            "unit": "Fahrenheit"
                        }
                    }
                ],
                "ingredients": [],
                "number": 1,
                "step": "Preheat the oven to 200 degrees F."
            },
            {
                "equipment": [
                    {
                        "id": 404661,
                        "image": "whisk.png",
                        "name": "whisk"
                    },
                    {
                        "id": 404783,
                        "image": "bowl.jpg",
                        "name": "bowl"
                    }
                ],
                "ingredients": [
                    {
                        "id": 19334,
                        "image": "light-brown-sugar.jpg",
                        "name": "light brown sugar"
                    },
                    {
                        "id": 19335,
                        "image": "sugar-in-bowl.png",
                        "name": "granulated sugar"
                    },
                    {
                        "id": 18371,
                        "image": "white-powder.jpg",
                        "name": "baking powder"
                    },
                    {
                        "id": 18372,
                        "image": "white-powder.jpg",
                        "name": "baking soda"
                    },
                    {
                        "id": 12142,
                        "image": "pecans.jpg",
                        "name": "pecans"
                    },
                    {
                        "id": 20081,
                        "image": "flour.png",
                        "name": "all purpose flour"
                    },
                    {
                        "id": 2047,
                        "image": "salt.jpg",
                        "name": "salt"
                    }
                ],
                "number": 2,
                "step": "Whisk together the flour, pecans, granulated sugar, light brown sugar, baking powder, baking soda, and salt in a medium bowl."
            },
            {
                "equipment": [
                    {
                        "id": 404661,
                        "image": "whisk.png",
                        "name": "whisk"
                    },
                    {
                        "id": 404783,
                        "image": "bowl.jpg",
                        "name": "bowl"
                    }
                ],
                "ingredients": [
                    {
                        "id": 2050,
                        "image": "vanilla-extract.jpg",
                        "name": "vanilla extract"
                    },
                    {
                        "id": 93622,
                        "image": "vanilla.jpg",
                        "name": "vanilla bean"
                    },
                    {
                        "id": 1230,
                        "image": "buttermilk.jpg",
                        "name": "buttermilk"
                    },
                    {
                        "id": 1123,
                        "image": "egg.png",
                        "name": "egg"
                    }
                ],
                "number": 3,
                "step": "Whisk together the eggs, buttermilk, butter and vanilla extract and vanilla bean in a small bowl."
            },
            {
                "equipment": [],
                "ingredients": [
                    {
                        "id": 1123,
                        "image": "egg.png",
                        "name": "egg"
                    }
                ],
                "number": 4,
                "step": "Add the egg mixture to the dry mixture and gently mix to combine. Do not overmix."
            },
            {
                "equipment": [],
                "ingredients": [],
                "length": {
                    "number": 15,
                    "unit": "minutes"
                },
                "number": 5,
                "step": "Let the batter sit at room temperature for at least 15 minutes and up to 30 minutes before using."
            },
            {
                "equipment": [
                    {
                        "id": 404779,
                        "image": "griddle.jpg",
                        "name": "griddle"
                    },
                    {
                        "id": 404645,
                        "image": "pan.png",
                        "name": "frying pan"
                    }
                ],
                "ingredients": [],
                "length": {
                    "number": 3,
                    "unit": "minutes"
                },
                "number": 6,
                "step": "Heat a cast iron or nonstick griddle pan over medium heat and brush with melted butter. Once the butter begins to sizzle, use 2 tablespoons of the batter for each pancake and cook until the bubbles appear on the surface and the bottom is golden brown, about 2 minutes, flip over and cook until the bottom is golden brown, 1 to 2 minutes longer."
            },
            {
                "equipment": [
                    {
                        "id": 404784,
                        "image": "oven.jpg",
                        "name": "oven",
                        "temperature": {
                            "number": 200.0,
                            "unit": "Fahrenheit"
                        }
                    }
                ],
                "ingredients": [],
                "number": 7,
                "step": "Transfer the pancakes to a platter and keep warm in a 200 degree F oven."
            },
            {
                "equipment": [],
                "ingredients": [
                    {
                        "id": 10014037,
                        "image": "bourbon.png",
                        "name": "bourbon"
                    }
                ],
                "number": 8,
                "step": "Serve 6 pancakes per person, top each with some of the bourbon butter."
            },
            {
                "equipment": [],
                "ingredients": [
                    {
                        "id": 19336,
                        "image": "powdered-sugar.jpg",
                        "name": "powdered sugar"
                    },
                    {
                        "id": 19911,
                        "image": "maple-syrup.png",
                        "name": "maple syrup"
                    }
                ],
                "number": 9,
                "step": "Drizzle with warm maple syrup and dust with confectioners' sugar."
            },
            {
                "equipment": [],
                "ingredients": [
                    {
                        "id": 12142,
                        "image": "pecans.jpg",
                        "name": "pecans"
                    }
                ],
                "number": 10,
                "step": "Garnish with fresh mint sprigs and more toasted pecans, if desired."
            }
        ]
    },
    {
        "name": "Bourbon Molasses Butter",
        "steps": [
            {
                "equipment": [
                    {
                        "id": 404669,
                        "image": "sauce-pan.jpg",
                        "name": "sauce pan"
                    }
                ],
                "ingredients": [
                    {
                        "id": 10014037,
                        "image": "bourbon.png",
                        "name": "bourbon"
                    },
                    {
                        "id": 19335,
                        "image": "sugar-in-bowl.png",
                        "name": "sugar"
                    }
                ],
                "number": 1,
                "step": "Combine the bourbon and sugar in a small saucepan and cook over high heat until reduced to 3 tablespoons, remove and let cool."
            },
            {
                "equipment": [
                    {
                        "id": 404771,
                        "image": "food-processor.png",
                        "name": "food processor"
                    }
                ],
                "ingredients": [
                    {
                        "id": 19304,
                        "image": "molasses.jpg",
                        "name": "molasses"
                    },
                    {
                        "id": 10014037,
                        "image": "bourbon.png",
                        "name": "bourbon"
                    },
                    {
                        "id": 2047,
                        "image": "salt.jpg",
                        "name": "salt"
                    }
                ],
                "number": 2,
                "step": "Put the butter, molasses, salt and cooled bourbon mixture in a food processor and process until smooth."
            },
            {
                "equipment": [
                    {
                        "id": 404730,
                        "image": "plastic-wrap.jpg",
                        "name": "plastic wrap"
                    },
                    {
                        "id": 404783,
                        "image": "bowl.jpg",
                        "name": "bowl"
                    }
                ],
                "ingredients": [],
                "number": 3,
                "step": "Scrape into a bowl, cover with plastic wrap and refrigerate for at least 1 hour to allow the flavors to meld."
            },
            {
                "equipment": [],
                "ingredients": [],
                "length": {
                    "number": 30,
                    "unit": "minutes"
                },
                "number": 4,
                "step": "Remove from the refrigerator about 30 minutes before using to soften."
            }
        ]
    }
]

Quotas

Extract Recipe from Website

This endpoint lets you extract recipe data such as title, ingredients, and instructions from any properly formatted Website.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{/* recipe data as in Get Recipe Information endpoint */}

Quotas

Ingredients by ID Widget

Visualize a recipe's ingredient list.

Headers

Request Headers:

• Accept: text/html

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and could look like this, for example:

Quotas

Ingredients by ID Image

Visualize a recipe's ingredient list.

Headers

Request Headers:

• Accept: image/png

Response Headers:

• Content-Type: image/png

Parameters

The response will be an image that may look like this:

Quotas

Recipe Taste by ID Widget

Get a recipe's taste. The tastes supported are sweet, salty, sour, bitter, savory, and fatty.

Headers

Request Headers:

• Accept: text/html

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and could look like this, for example:

Quotas

Recipe Taste by ID Image

Get a recipe's taste as an image. The tastes supported are sweet, salty, sour, bitter, savory, and fatty.

Headers

Request Headers:

• Accept: image/png

Response Headers:

• Content-Type: image/png

Parameters

The response will be an image that may look like this:

Quotas

Equipment by ID Widget

Visualize a recipe's equipment list.

Headers

Request Headers:

• Accept: text/html

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and could look like this, for example:

Quotas

Equipment by ID Image

Visualize a recipe's equipment list as an image.

Headers

Request Headers:

• Accept: image/png

Response Headers:

• Content-Type: image/png

Parameters

The response will be an image that may look like this:

Quotas

Price Breakdown by ID Widget

Visualize a recipe's price breakdown.

Headers

Request Headers:

• Accept: text/html

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and and could look like this, for example:

Quotas

Price Breakdown by ID Image

Visualize a recipe's price breakdown.

Headers

Request Headers:

• Accept: image/png

Response Headers:

• Content-Type: image/png

Parameters

The response will be an image that may look like this:

Quotas

Recipe Taste Widget

Visualize a recipe's taste information as HTML including CSS. You can play around with that endpoint!

Full example code of how to work with widgets can be found in our spoonacular-widget GitHub.

Headers

Request Headers:

• Accept: text/html
• Content-Type: application/x-www-form-urlencoded

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and and could look like this, for example:

Quotas

Recipe Nutrition Widget

Visualize a recipe's nutritional information as HTML including CSS. You can play around with that endpoint!

Full example code of how to work with widgets can be found in our spoonacular-widget GitHub.

Headers

Request Headers:

• Accept: text/html
• Content-Type: application/x-www-form-urlencoded

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and and could look like this, for example:

Quotas

Price Breakdown Widget

Visualize the price breakdown of a recipe. You can play around with that endpoint!

Full example code of how to work with widgets can be found in our spoonacular-widget GitHub.

Headers

Request Headers:

• Accept: text/html
• Content-Type: application/x-www-form-urlencoded

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and could look like this, for example::

Quotas

Equipment Widget

Visualize the equipment used to make a recipe. You can play around with that endpoint!

Full example code of how to work with widgets can be found in our spoonacular-widget GitHub.

Headers

Request Headers:

• Accept: text/html
• Content-Type: application/x-www-form-urlencoded

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and could look like this, for example:

Quotas

Analyze Recipe

This endpoint allows you to send raw recipe information, such as title, servings, and ingredients, to then see what we compute (badges, diets, nutrition, and more). This is useful if you have your own recipe data and want to enrich it with our semantic analysis.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "title": "Spaghetti Carbonara",
    "servings": 2,
    "ingredients": [
        "1 lb spaghetti",
        "3.5 oz pancetta",
        "2 Tbsps olive oil",
        "1  egg",
        "0.5 cup parmesan cheese"
    ],
    "instructions": "Bring a large pot of water to a boil and season generously with salt. Add the pasta to the water once boiling and cook until al dente. Reserve 2 cups of cooking water and drain the pasta. "
}

/* recipe data as in Get Recipe Information endpoint */

Quotas

Summarize Recipe

Automatically generate a short description that summarizes key information about the recipe.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "id": 4632,
    "summary": "The recipe Soy-and-Ginger-Glazed Salmon with Udon Noodles can be made  <b>in approximately 1 hour and 35 minutes </b>. One portion of this dish contains about  <b>48g of protein </b>,  <b>17g of fat </b>, and a total of  <b>552 calories </b>. This recipe serves 4. For  <b>$5.91 per serving </b>, this recipe  <b>covers 47% </b> of your daily requirements of vitamins and minerals. It works well as a main course. 1 person has tried and liked this recipe. It is brought to you by Food and Wine. If you have fresh ginger, udon noodles, salmon fillets, and a few other ingredients on hand, you can make it. It is a good option if you're following a  <b>dairy free and pescatarian </b> diet. All things considered, we decided this recipe  <b>deserves a spoonacular score of 92% </b>. This score is great. If you like this recipe, take a look at these similar recipes: Salmon With Soy-ginger Noodles, Ginger-Soy Salmon With Soba Noodles, and Soy & ginger salmon with soba noodles.",
    "title": "Soy-and-Ginger-Glazed Salmon with Udon Noodles"
}

Quotas

Create Recipe Card

Generate a recipe card for a recipe.

Headers

Request Headers:

• Content-Type: multipart/form-data

Response Headers:

• Content-Type: application/json

Parameters

{
    "url": "https://spoonacular.com/url-to-generated-recipe-card.jpg"
}

The API response will contain a link to the generated image. It could look like this for example:

Quotas

Create Recipe Card

Generate a recipe card for a recipe.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "url": "https://spoonacular.com/url-to-generated-recipe-card.jpg",
}

The API response will contain a link to the generated image. It could look like this for example:

Quotas

Analyze Recipe Instructions

This endpoint allows you to break down instructions into atomic steps. Furthermore, each step will contain the ingredients and equipment required. Additionally, all ingredients and equipment from the recipe's instructions will be extracted independently of the step they're used in.

Headers

Request Headers:

• Content-Type: application/x-www-form-urlencoded

Response Headers:

• Content-Type: application/json

Parameters

{
    "parsedInstructions": [
        {
            "name": "",
            "steps": [
                {
                    "number": 1,
                    "step": "Put the garlic in a pan and then add the onion.",
                    "ingredients": [
                        {
                            "id": 11215,
                            "name": "garlic",
                            "localizedName": "garlic",
                            "image": "garlic.png"
                        },
                        {
                            "id": 11282,
                            "name": "onion",
                            "localizedName": "onion",
                            "image": "brown-onion.png"
                        }
                    ],
                    "equipment": [
                        {
                            "id": 404645,
                            "name": "frying pan",
                            "localizedName": "frying pan",
                            "image": "pan.png"
                        }
                    ]
                },
                {
                    "number": 2,
                    "step": "Add some salt and oregano.",
                    "ingredients": [
                        {
                            "id": 2027,
                            "name": "oregano",
                            "localizedName": "oregano",
                            "image": "oregano.jpg"
                        },
                        {
                            "id": 2047,
                            "name": "salt",
                            "localizedName": "salt",
                            "image": "salt.jpg"
                        }
                    ],
                    "equipment": []
                }
            ]
        }
    ],
    "ingredients": [
        {
            "id": 2027,
            "name": "oregano"
        },
        {
            "id": 11215,
            "name": "garlic"
        },
        {
            "id": 11282,
            "name": "onion"
        },
        {
            "id": 2047,
            "name": "salt"
        }
    ],
    "equipment": [
        {
            "id": 404645,
            "name": "frying pan"
        }
    ]
}

Quotas

Classify Cuisine

Classify the recipe's cuisine.

Headers

Request Headers:

• Content-Type: application/x-www-form-urlencoded

Response Headers:

• Content-Type: application/json

Parameters

{
    "cuisine": "Mediterranean",
    "cuisines": [
        "Mediterranean",
        "European",
        "Italian"
    ],
    "confidence": 0.0
}

Quotas

Analyze a Recipe Search Query

Parse a recipe search query to find out its intention.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "dishes": [
        {
            "image": "https://img.spoonacular.com/ingredients_100x100/salmon.png",
            "name": "salmon"
        }
    ],
    "ingredients": [
        {
            "image": "fusilli.jpg",
            "include": true,
            "name": "fusilli"
        },
        {
            "image": "nuts-mixed.jpg",
            "include": false,
            "name": "nuts mixed"
        }
    ],
    "cuisines": [],
    "modifiers": []
}

Quotas

Convert Amounts

Convert amounts like "2 cups of flour to grams".

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "sourceAmount": 2.5,
    "sourceUnit": "cups",
    "targetAmount": 312.5,
    "targetUnit": "grams",
    "answer": "2.5 cups flour translates to 312.5 grams."
}

Quotas

Parse Ingredients

Extract an ingredient from plain text.

Headers

Request Headers:

• Content-Type: application/x-www-form-urlencoded

Response Headers:

• Content-Type: application/json

Parameters

[
    {
        "id": 10014355,
        "original": "1 cup green tea",
        "originalName": "green tea",
        "name": "tea",
        "nameClean": "green tea",
        "amount": 1.0,
        "unit": "cup",
        "unitShort": "cup",
        "unitLong": "cup",
        "possibleUnits": [
            "g",
            "oz",
            "fluid ounce",
            "cup"
        ],
        "estimatedCost": {
            "value": 1786.86,
            "unit": "US Cents"
        },
        "consistency": "solid",
        "aisle": "Tea and Coffee",
        "image": "green-tea-leaves.jpg",
        "meta": [
            "green"
        ],
        "nutrition": {
            "nutrients": [
                {
                    "name": "Calories",
                    "amount": 2.36,
                    "unit": "kcal",
                    "percentOfDailyNeeds": 0.12
                },
                {
                    "name": "Fat",
                    "amount": 0.0,
                    "unit": "g",
                    "percentOfDailyNeeds": 0.0
                },
                {
                    "name": "Saturated Fat",
                    "amount": 0.0,
                    "unit": "g",
                    "percentOfDailyNeeds": 0.03
                },
                {
                    "name": "Carbohydrates",
                    "amount": 0.71,
                    "unit": "g",
                    "percentOfDailyNeeds": 0.24
                },
                {
                    "name": "Net Carbohydrates",
                    "amount": 0.71,
                    "unit": "g",
                    "percentOfDailyNeeds": 0.26
                },
                {
                    "name": "Sugar",
                    "amount": 0.0,
                    "unit": "g",
                    "percentOfDailyNeeds": 0.0
                },
                {
                    "name": "Cholesterol",
                    "amount": 0.0,
                    "unit": "mg",
                    "percentOfDailyNeeds": 0.0
                },
                {
                    "name": "Sodium",
                    "amount": 7.08,
                    "unit": "mg",
                    "percentOfDailyNeeds": 0.31
                },
                {
                    "name": "Caffeine",
                    "amount": 47.2,
                    "unit": "mg",
                    "percentOfDailyNeeds": 15.73
                },
                {
                    "name": "Protein",
                    "amount": 0.0,
                    "unit": "g",
                    "percentOfDailyNeeds": 0.0
                },
                {
                    "name": "Manganese",
                    "amount": 0.52,
                    "unit": "mg",
                    "percentOfDailyNeeds": 25.84
                },
                {
                    "name": "Folate",
                    "amount": 11.8,
                    "unit": "µg",
                    "percentOfDailyNeeds": 2.95
                },
                {
                    "name": "Potassium",
                    "amount": 87.32,
                    "unit": "mg",
                    "percentOfDailyNeeds": 2.49
                },
                {
                    "name": "Vitamin B2",
                    "amount": 0.03,
                    "unit": "mg",
                    "percentOfDailyNeeds": 1.94
                },
                {
                    "name": "Magnesium",
                    "amount": 7.08,
                    "unit": "mg",
                    "percentOfDailyNeeds": 1.77
                },
                {
                    "name": "Copper",
                    "amount": 0.02,
                    "unit": "mg",
                    "percentOfDailyNeeds": 1.18
                }
            ],
            "properties": [
                {
                    "name": "Glycemic Index",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Glycemic Load",
                    "amount": 0.0,
                    "unit": ""
                }
            ],
            "flavonoids": [
                {
                    "name": "Cyanidin",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Petunidin",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Delphinidin",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Malvidin",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Pelargonidin",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Peonidin",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Catechin",
                    "amount": 3.56,
                    "unit": "mg"
                },
                {
                    "name": "Epigallocatechin",
                    "amount": 19.0,
                    "unit": "mg"
                },
                {
                    "name": "Epicatechin",
                    "amount": 5.03,
                    "unit": "mg"
                },
                {
                    "name": "Epicatechin 3-gallate",
                    "amount": 13.83,
                    "unit": "mg"
                },
                {
                    "name": "Epigallocatechin 3-gallate",
                    "amount": 22.09,
                    "unit": "mg"
                },
                {
                    "name": "Theaflavin",
                    "amount": 3.73,
                    "unit": "mg"
                },
                {
                    "name": "Thearubigins",
                    "amount": 191.87,
                    "unit": "mg"
                },
                {
                    "name": "Eriodictyol",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Hesperetin",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Naringenin",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Apigenin",
                    "amount": 0.0,
                    "unit": "mg"
                },
                {
                    "name": "Luteolin",
                    "amount": 0.0,
                    "unit": "mg"
                },
                {
                    "name": "Isorhamnetin",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Kaempferol",
                    "amount": 3.33,
                    "unit": "mg"
                },
                {
                    "name": "Myricetin",
                    "amount": 1.06,
                    "unit": "mg"
                },
                {
                    "name": "Quercetin",
                    "amount": 5.17,
                    "unit": "mg"
                },
                {
                    "name": "Theaflavin-3,3'-digallate",
                    "amount": 4.13,
                    "unit": "mg"
                },
                {
                    "name": "Theaflavin-3'-gallate",
                    "amount": 3.56,
                    "unit": "mg"
                },
                {
                    "name": "Theaflavin-3-gallate",
                    "amount": 0.0,
                    "unit": ""
                },
                {
                    "name": "Gallocatechin",
                    "amount": 2.95,
                    "unit": "mg"
                }
            ],
            "caloricBreakdown": {
                "percentProtein": 0.0,
                "percentFat": 0.0,
                "percentCarbs": 100.0
            },
            "weightPerServing": {
                "amount": 236,
                "unit": "g"
            }
        }
    }
]

Quotas

Compute Glycemic Load

Retrieve the glycemic index for a list of ingredients and compute the individual and total glycemic load.

Headers

Request Headers:

• Content-Type: application/json

Response Headers:

• Content-Type: application/json

Parameters

{
    "ingredients":[
        "1 kiwi",
        "2 cups rice",
        "2 glasses of water"
    ]
}

{
    "totalGlycemicLoad": 183.64,
    "ingredients": [
        {
            "id": 9148,
            "original": "1 kiwi",
            "glycemicIndex": 52.67,
            "glycemicLoad": 5.59
        },
        {
            "id": 20444,
            "original": "2 cups rice",
            "glycemicIndex": 61.19,
            "glycemicLoad": 178.05
        },
        {
            "id": 14412,
            "original": "2 glasses of water",
            "glycemicIndex": 0.0,
            "glycemicLoad": 0.0
        }
    ]
}

Quotas

Autocomplete Ingredient Search

Autocomplete the entry of an ingredient.

Headers

Response Headers:

• Content-Type: application/json

Parameters

[
    {
        "name": "apple",
        "image": "apple.jpg",
        "id": 9003,
        "aisle": "Produce",
        "possibleUnits": [
            "small",
            "large",
            "piece",
            "slice",
            "g",
            "extra small",
            "medium",
            "oz",
            "cup slice",
            "cup",
            "serving"
        ]
    },
    {
        "name": "applesauce",
        "image": "applesauce.png",
        "id": 9019,
        "aisle": "Canned and Jarred",
        "possibleUnits": [
            "g",
            "oz",
            "cup",
            "serving",
            "tablespoon"
        ]
    },
    {
        "name": "apple juice",
        "image": "apple-juice.jpg",
        "id": 9016,
        "aisle": "Beverages",
        "possibleUnits": [
            "g",
            "drink box",
            "fl oz",
            "oz",
            "teaspoon",
            "cup",
            "serving",
            "tablespoon"
        ]
    },
    {
        "name": "apple cider",
        "image": "apple-cider.jpg",
        "id": 1009016,
        "aisle": "Beverages",
        "possibleUnits": [
            "g",
            "drink box",
            "fl oz",
            "oz",
            "teaspoon",
            "bottle NFS",
            "cup",
            "serving",
            "tablespoon"
        ]
    },
    {
        "name": "apple jelly",
        "image": "apple-jelly.jpg",
        "id": 10019297,
        "aisle": "Nut butters, Jams, and Honey",
        "possibleUnits": [
            "g",
            "oz",
            "packet",
            "teaspoon",
            "cup",
            "serving",
            "tablespoon"
        ]
    }
]

Quotas

Ingredient Search

Search for simple whole foods (e.g. fruits, vegetables, nuts, grains, meat, fish, dairy etc.).

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "results": [
        {
            "id": 19400,
            "name": "banana chips",
            "image": "banana-chips.jpg"
        },
        {
            "id": 93779,
            "name": "banana liqueur",
            "image": "limoncello.jpg"
        }
    ],
    "offset": 0,
    "number": 2,
    "totalResults": 13
}

Quotas

Get Ingredient Substitutes

Search for substitutes for a given ingredient.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "ingredient": "butter",
    "substitutes": [
        "1 cup = 7/8 cup shortening and 1/2 tsp salt",
        "1 cup = 7/8 cup vegetable oil + 1/2 tsp salt",
        "1/2 cup = 1/4 cup buttermilk + 1/4 cup unsweetened applesauce",
        "1 cup = 1 cup margarine"
    ],
    "message": "Found 4 substitutes for the ingredient."
}

Quotas

Get Ingredient Substitutes by ID

Search for substitutes for a given ingredient.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "ingredient": "butter",
    "substitutes": [
        "1 cup = 7/8 cup shortening and 1/2 tsp salt",
        "1 cup = 7/8 cup vegetable oil + 1/2 tsp salt",
        "1/2 cup = 1/4 cup buttermilk + 1/4 cup unsweetened applesauce",
        "1 cup = 1 cup margarine"
    ],
    "message": "Found 4 substitutes for the ingredient."
}

Quotas

Compute Ingredient Amount

Compute the amount you need of a certain ingredient for a certain nutritional goal. For example, how much pineapple do you have to eat to get 10 grams of protein?

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "amount": 65.32,
    "unit": "oz"
}

Quotas

Ingredients Widget

Visualize ingredients of a recipe. You can play around with that endpoint!

Full example code of how to work with widgets can be found in our spoonacular-widget GitHub.

Headers

Request Headers:

• Accept: text/html
• Content-Type: application/x-www-form-urlencoded

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and could look like this, for example:

Quotas

Get Product Information

Use a product id to get full information about a product, such as ingredients, nutrition, etc. The nutritional information is per serving.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "id": 22347,
    "title": "SNICKERS Minis Size Chocolate Candy Bars Variety Mix 10.5-oz. Bag",
    "breadcrumbs": [
        "bars"
    ],
    "imageType": "jpg",
    "badges": [
        "msg_free",
        "no_artificial_colors",
        "no_artificial_flavors",
        "no_artificial_ingredients",
        "gluten_free"
    ],
    "importantBadges": [
        "no_artificial_flavors",
        "no_artificial_colors",
        "no_artificial_ingredients",
        "gluten_free",
        "msg_free"
    ],
    "ingredientCount": 32,
    "generatedText": null,
    "ingredientList": "Snickers Brand Almond Bar: Milk Chocolate (Sugar, Cocoa Butter, Chocolate, Skim Milk, Lactose, Milkfat, Soy Lecithin, Artificial Flavor), Corn Syrup, Almonds, Sugar, Milkfat, Skim Milk, Less than 2% - Lactose, Salt, Hydrogenated Palm Kernel Oil and/or Palm Oil, Egg Whites, Chocolate, Artificial Flavor. Snickers Brand: Milk Chocolate (Sugar, Cocoa Butter, Chocolate, Skim Milk, Lactose, Milkfat, Soy Lecithin, Artificial Flavor), Peanuts, Corn Syrup, Sugar, Milkfat, Skim Milk, Partially Hydrogenated Soybean Oil, Lactose, Salt, Egg Whites, Chocolate, Artificial Flavor. Snickers Brand Peanut Butter Squared Bars: Milk Chocolate (Sugar, Cocoa Butter, Chocolate, Skim Milk, Lactose, Milkfat, Soy Lecithin, Artificial Flavor), Peanut Butter (Peanuts, Partially Hydrogenated Soybean Oil), Peanuts, Sugar, Corn Syrup, Vegetable Oil (Hydrogenated Palm Kernel Oil, Palm Oil, Rapeseed Oil and Cottonseed Oil and/or Partially Hydrogenated Palm Kernel Oil), Lactose, Corn Syrup Solids, Invert Sugar, Less than 2% - Glycerin, Dextrose, Skim Milk, Salt, Calcium Carbonate, Partially Hydrogenated Soybean Oil, Egg Whites, Artificial Flavor, TBHQ to Maintain Freshness",
    "ingredients": [
        {
            "description": null,
            "name": "emulsifier",
            "safety_level": null
        },
        {
            "description": null,
            "name": "added sugar",
            "safety_level": null
        },
        {
            "description": null,
            "name": "sweetener",
            "safety_level": null
        },
        {
            "description": null,
            "name": "cooking fat",
            "safety_level": null
        },
        {
            "description": null,
            "name": "cooking oil",
            "safety_level": null
        },
        {
            "description": null,
            "name": "lecithin",
            "safety_level": null
        },
        {
            "description": null,
            "name": "yeast",
            "safety_level": null
        },
        {
            "description": null,
            "name": "menu item type",
            "safety_level": null
        },
        {
            "description": null,
            "name": "nuts",
            "safety_level": null
        },
        {
            "description": null,
            "name": "partially hydrogenated vegetable oil",
            "safety_level": "low"
        },
        {
            "description": "Unlike partially hydrogenated oils, fully hydrogenated oils do not contain trans fat and thus are currently considered safer.",
            "name": "hydrogenated vegetable oil",
            "safety_level": "high"
        },
        {
            "description": null,
            "name": "calcium",
            "safety_level": null
        },
        {
            "description": null,
            "name": "nut butter",
            "safety_level": null
        },
        {
            "description": null,
            "name": "legumes",
            "safety_level": null
        },
        {
            "description": null,
            "name": "refined sweetener",
            "safety_level": null
        },
        {
            "description": null,
            "name": "non food item",
            "safety_level": null
        },
        {
            "description": null,
            "name": "tree nuts",
            "safety_level": null
        },
        {
            "description": null,
            "name": "chocolate",
            "safety_level": null
        },
        {
            "description": null,
            "name": "sugar",
            "safety_level": null
        },
        {
            "description": null,
            "name": "snack",
            "safety_level": null
        },
        {
            "description": null,
            "name": "corn syrup",
            "safety_level": null
        },
        {
            "description": null,
            "name": "drink",
            "safety_level": null
        },
        {
            "description": null,
            "name": "milk",
            "safety_level": null
        },
        {
            "description": null,
            "name": "spread",
            "safety_level": null
        },
        {
            "description": null,
            "name": "vegetable oil",
            "safety_level": null
        },
        {
            "description": null,
            "name": "yeast nutrient",
            "safety_level": null
        },
        {
            "description": null,
            "name": "palm kernel oil",
            "safety_level": null
        },
        {
            "description": null,
            "name": "artificial ingredient",
            "safety_level": null
        },
        {
            "description": null,
            "name": "stabilizer",
            "safety_level": null
        },
        {
            "description": null,
            "name": "additive",
            "safety_level": null
        },
        {
            "description": null,
            "name": "nutrient",
            "safety_level": null
        },
        {
            "description": null,
            "name": "soybean oil",
            "safety_level": null
        },
        {
            "description": null,
            "name": "supplement",
            "safety_level": null
        },
        {
            "description": null,
            "name": "mineral",
            "safety_level": null
        },
        {
            "description": null,
            "name": "artificial flavor",
            "safety_level": "medium"
        },
        {
            "description": null,
            "name": "skim milk",
            "safety_level": null
        },
        {
            "description": null,
            "name": "peanuts",
            "safety_level": null
        },
        {
            "description": null,
            "name": "corn syrup solids",
            "safety_level": "medium"
        },
        {
            "description": "Unlike partially hydrogenated oils, fully hydrogenated oils do not contain trans fat and thus are currently considered safer.",
            "name": "hydrogenated palm kernel oil",
            "safety_level": "high"
        },
        {
            "description": null,
            "name": "cottonseed oil",
            "safety_level": null
        },
        {
            "description": null,
            "name": "milkfat",
            "safety_level": "high"
        },
        {
            "description": null,
            "name": "lactose",
            "safety_level": null
        },
        {
            "description": null,
            "name": "corn syrup",
            "safety_level": null
        },
        {
            "description": null,
            "name": "cocoa butter",
            "safety_level": "high"
        },
        {
            "description": null,
            "name": "tbhq to maintain freshness",
            "safety_level": null
        },
        {
            "description": null,
            "name": "peanut butter",
            "safety_level": null
        },
        {
            "description": null,
            "name": "egg whites",
            "safety_level": null
        },
        {
            "description": null,
            "name": "sugar",
            "safety_level": null
        },
        {
            "description": null,
            "name": "milk chocolate",
            "safety_level": null
        },
        {
            "description": null,
            "name": "palm oil",
            "safety_level": null
        },
        {
            "description": null,
            "name": "artificial flavor",
            "safety_level": null
        },
        {
            "description": null,
            "name": "salt",
            "safety_level": null
        },
        {
            "description": null,
            "name": "almonds",
            "safety_level": null
        },
        {
            "description": null,
            "name": "skim milk less than 2% - lactose",
            "safety_level": null
        },
        {
            "description": null,
            "name": "vegetable oil",
            "safety_level": null
        },
        {
            "description": null,
            "name": "less than 2% - glycerin",
            "safety_level": null
        },
        {
            "description": null,
            "name": "dextrose",
            "safety_level": "high"
        },
        {
            "description": "Soy lecithin is not a concern for most people allergic to soy.",
            "name": "soy lecithin",
            "safety_level": "high"
        },
        {
            "description": null,
            "name": "invert sugar",
            "safety_level": "high"
        },
        {
            "description": null,
            "name": "chocolate",
            "safety_level": null
        },
        {
            "description": null,
            "name": "rapeseed oil",
            "safety_level": null
        },
        {
            "description": null,
            "name": "partially hydrogenated soybean oil",
            "safety_level": "low"
        },
        {
            "description": null,
            "name": "calcium carbonate",
            "safety_level": "high"
        },
        {
            "description": null,
            "name": "partially hydrogenated palm kernel oil",
            "safety_level": "low"
        },
        {
            "description": null,
            "name": "artificial flavor.snickers brand",
            "safety_level": null
        },
        {
            "description": null,
            "name": "snickers brand almond bar",
            "safety_level": null
        }
    ],
    "likes": 0,
    "aisle": "Sweet Snacks",
    "nutrition": {
        "nutrients": [
            {
                "name": "Fat",
                "amount": 4,
                "unit": "g",
                "percentOfDailyNeeds": 6.15
            },
            {
                "name": "Protein",
                "amount": 10,
                "unit": "g",
                "percentOfDailyNeeds": 20
            },
            {
                "name": "Calories",
                "amount": 200,
                "unit": "cal",
                "percentOfDailyNeeds": 10
            },
            {
                "name": "Carbohydrates",
                "amount": 26,
                "unit": "g",
                "percentOfDailyNeeds": 9.45
            }
        ],
        "caloricBreakdown": {
            "percentProtein": 22.22,
            "percentFat": 20,
            "percentCarbs": 57.78
        }
    },
    "price": 324.0,
    "servings": {
        "number": 8,
        "size": 4,
        "unit": "pieces"
    },
    "spoonacularScore": 0.0
}

Quotas

Grocery Products

The spoonacular grocery products API allows you to search through all products. You can find products by query (e.g. "pizza") and/or by macro-nutrients (e.g. <500 calories).

Once you found a product, you can get a lot of detailed information about it such as nutrition, ingredients, cost, and where to find it in the supermarket.

spoonacular analyzes every product and tries to retrieve meta information. This information is stored in badges.

Here is a list of all possible badges a product can have:

• egg_free
• wheat_free
• grain_free
• peanut_free
• primal
• vegetarian
• nut_free
• vegan
• pescetarian
• dairy_free
• gluten_free
• paleo
• msg_free
• no_artificial_colors
• no_artificial_flavors
• no_artificial_ingredients
• grass_fed
• no_added_sugar
• pasture_raised
• free_range
• cage_free
• wild_caught
• fair_trade
• no_additives
• hormone_free
• no_preservatives
• sugar_free
• sulfite_free
• corn_free
• soy_free
• nitrate_free
• gmo_free
• organic
• kosher
• halal
• sustainable
• non_alcoholic
• lactose_free
• whole_grain
• whole_wheat
• multigrain
• sprouted_grain

Search Grocery Products

Search packaged food products, such as frozen pizza or Greek yogurt.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "products": [
        {
            "id": 192386,
            "title": "Pizza Buddy: Frozen Pizza Dough, 16 Oz",
            "imageType": "jpg"
        },
        {
            "id": 27693,
            "title": "Uno Pizza",
            "imageType": "jpg"
        }
    ],
    "totalProducts": 1258,
    "type": "product",
    "offset": 0,
    "number": 2
}

Quotas

Search Grocery Products by UPC

Get information about a packaged food using its UPC.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "id": 30004,
    "title": "Swan Flour",
    "badges": [
        "egg_free",
        "wheat_free",
        "grain_free",
        "peanut_free",
        "primal",
        "vegetarian",
        "nut_free",
        "vegan",
        "pescetarian",
        "dairy_free",
        "paleo",
        "gluten_free"
    ],
    "importantBadges": [
        "gluten_free",
        "paleo",
        "primal",
        "wheat_free",
        "grain_free"
    ],
    "breadcrumbs": [
        "flour"
    ],
    "generatedText": "Swan Flour: This product is an awesome fit if you are searching for a healthy flour. This product has 1 ingredient (in our experience: the fewer ingredients, the better!) This product contains no ingredients that some research suggests you should avoid. One serving of this product provides 30 calories, 0g grams of fat, 0g grams of protein, and 8g grams of carbs.",
    "imageType": "jpg",
    "ingredientCount": null,
    "ingredientList": "Potato Starch",
    "ingredients": [
        {
            "description": null,
            "name": "",
            "safety_level": null
        },
        {
            "description": null,
            "name": "starch",
            "safety_level": null
        },
        {
            "description": null,
            "name": "potato starch",
            "safety_level": null
        }
    ],
    "likes": 0,
    "nutrition": {
        "nutrients": [
            {
                "name": "Fat",
                "amount": 0,
                "unit": "g",
                "percentOfDailyNeeds": 0
            },
            {
                "name": "Protein",
                "amount": 0,
                "unit": "g",
                "percentOfDailyNeeds": 0
            },
            {
                "name": "Calories",
                "amount": 30,
                "unit": "cal",
                "percentOfDailyNeeds": 10
            },
            {
                "name": "Carbohydrates",
                "amount": 8,
                "unit": "g",
                "percentOfDailyNeeds": 9.45
            }
        ],
        "caloricBreakdown": {
            "percentProtein": 22.22,
            "percentFat": 20,
            "percentCarbs": 57.78
        }
    },
    "price": 0.0,
    "servings": {
        "number": 34,
        "size": 1,
        "unit": "tbsp"
    },
    "spoonacularScore": 99.0,
    "credits": {
        "text": "openfoodtacts.org under (ODbL) v1.0",
        "link": "https://opendatacommons.org/licenses/odbl/1-0/",
        "image": "openfoodfacts.org under CC BY-SA 3.0 DEED",
        "imageLink": "https://creativecommons.org/licenses/by-sa/3.0/deed.en"
    }
}

Quotas

Search Custom Foods

Search custom foods in a user's account.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "customFoods": [
        {
            "id": 15,
            "title": "Max Cafe Curry Bratwurst",
            "servings": 1,
            "imageUrl": "https://img.spoonacular.com/ingredients_100x100/bratwurst.jpg",
            "price": 6.9
        }
    ],
    "type": "customFood",
    "offset": 0,
    "number": 10
}

Quotas

Add Custom Foods

Add custom foods to a user's account. This could be something as simple as "1 banana" or even mini recipes like "1 toast with jam".

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

Here's the sample post request. The "id" should only be sent if you update an existing custom food for the user. Only "title" and "servings" is required, everything else is optional.

The response will be the custom food's id. If an image is available you can get it via https://img.spoonacular.com/custom-foods/#ID#-90x90.jpg where #ID# is the custom food's id.

{
    "id": 1,
    "title": "Chickpea Lunchbox",
    "servings": 1,
    "customFoodBoxId": 123,
    "nutrition": {
        "calories": 300
    },
    "meta": {"diets":["vegan","vegetarian"],"intolerances":["sesame","soy"]},
    "imageUrl": "https://images.unsplash.com/photo-1543353071-c953d88f7033?q=80&w=500&auto=format&fit=crop"
}

Quotas

Get Comparable Products

Find comparable products to the given one.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "comparableProducts": {
        "calories": [],
        "likes": [],
        "price": [],
        "protein": [
            {
                "difference": 3,
                "id": 11797,
                "image": "https://img.spoonacular.com/products/11797.jpg",
                "title": "Casa Visco Capers"
            },
            {
                "difference": 1,
                "id": 90962,
                "image": "https://img.spoonacular.com/products/90962.jpg",
                "title": "Colavita Capers"
            },
            {
                "difference": 1,
                "id": 88139,
                "image": "https://img.spoonacular.com/products/88139.jpg",
                "title": "Mezzetta Capers"
            },
            {
                "difference": 1,
                "id": 152832,
                "image": "https://spoonacular.com/com/productImages/152832.jpg",
                "title": "Victoria Imported Capers"
            }
        ],
        "spoonacularScore": [
            {
                "difference": 7,
                "id": 125354,
                "image": "https://img.spoonacular.com/products/125354.jpg",
                "title": "DeLallo Capers"
            },
            {
                "difference": 7,
                "id": 118361,
                "image": "https://spoonacular.com/com/productImages/118361.jpg",
                "title": "Haddon House Non Pareil Capers"
            },
            {
                "difference": 7,
                "id": 113686,
                "image": "https://img.spoonacular.com/products/113686.jpg",
                "title": "Dell Alpe Capers"
            },
            {
                "difference": 7,
                "id": 112078,
                "image": "https://img.spoonacular.com/products/112078.jpg",
                "title": "Paesana Imported Capers"
            }
        ],
        "sugar": []
    }
}

Quotas

Autocomplete Product Search

Generate suggestions for grocery products based on a (partial) query. The matches will be found by looking in the title only.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "results": [
        {
            "id": 208698,
            "title": "buddig premium deli chicken breast - rotisserie flavored"
        },
        {
            "id": 41291,
            "title": "tyson all natural chicken breasts tenderloins"
        }
    ]
}

Quotas

Product Nutrition by ID Widget

Visualize a product's nutritional information as HTML including CSS.

Headers

Request Headers:

• Accept: text/html

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and could look like this, for example:

Quotas

Product Nutrition by ID Image

Visualize a product's nutritional information as an image.

Headers

Request Headers:

• Accept: image/png

Response Headers:

• Content-Type: image/png

Parameters

The response will be an image that may look like this:

Quotas

Recipe Nutrition by ID Widget

Visualize a recipe's nutritional information as HTML including CSS.

Headers

Request Headers:

• Accept: text/html

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and could look like this, for example:

Quotas

Recipe Nutrition by ID Image

Visualize a recipe's nutritional information as an image.

Headers

Request Headers:

• Accept: image/png

Response Headers:

• Content-Type: image/png

Parameters

The response will be an image that may look like this:

Quotas

Classify Grocery Product

This endpoint allows you to match a packaged food to a basic category, e.g. a specific brand of milk to the category milk.

Headers

Request Headers:

• Content-Type: application/json

Response Headers:

• Content-Type: application/json

Parameters

{
    "cleanTitle": "Kroger Vitamin A & D Reduced Fat 2% Milk",
    "image": "https://img.spoonacular.com/ingredients_100x100/milk.png",
    "category": "2 percent milk",
    "breadcrumbs": [
        "2 percent milk",
        "milk",
        "drink",
        "ingredient"
    ],
    "usdaCode": 1174
}

Quotas

Classify Grocery Product Bulk

Provide a set of product jsons, get back classified products.

Headers

Request Headers:

• Content-Type: application/json

Response Headers:

• Content-Type: application/json

Parameters

[
        { /* see classify grocery product result */ }
]

Quotas

Map Ingredients to Grocery Products

Map a set of ingredients to products you can buy in the grocery store.

Headers

Request Headers:

• Content-Type: application/json

Response Headers:

• Content-Type: application/json

Parameters

[
    {
        "original": "eggs",
        "originalName": "eggs",
        "ingredientImage": "egg.png",
        "meta": [
            "egg"
        ],
        "products": [
            {
                "id": 209945,
                "title": "Crystal Farms Eggs - Fresh Accents Peeled Hard Cooked 2 ct Packs",
                "upc": "075925889498"
            },
            {
                "id": 214723,
                "title": "Organic Valley Eggs - Organic Medium Brown",
                "upc": "093966811100"
            },
            {
                "id": 183228,
                "title": "Eggland's Best Grade A Eggs Jumbo - 12 CT",
                "upc": "715141328615"
            }
        ]
    },
    {
        "ingredientImage": "raw-bacon.png",
        "meta": [
            "bacon"
        ],
        "original": "bacon",
        "originalName": "bacon",
        "products": [
            {
                "id": 159164,
                "title": "Wright Bacon - Naturally Hickory Smoked",
                "upc": "079621461552"
            },
            {
                "id": 87924,
                "title": "Sugardale Bacon",
                "upc": "073890006025"
            },
            {
                "id": 213315,
                "title": "John Morrell Bacon - Applewood Smoked",
                "upc": "070100060877"
            },
            {
                "id": 94585,
                "title": "Hormel Black Label Bacon Thick Cut",
                "upc": "037600153041"
            }          
        ]
    }
]

Quotas

Guess Nutrition by Dish Name

Estimate the macronutrients of a dish based on its title.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "calories": {
        "confidenceRange95Percent": {
            "max": 574.07,
            "min": 389.92
        },
        "standardDeviation": 148.55,
        "unit": "calories",
        "value": 428.0
    },
    "carbs": {
        "confidenceRange95Percent": {
            "max": 78.19,
            "min": 55.54
        },
        "standardDeviation": 18.27,
        "unit": "g",
        "value": 65.0
    },
    "fat": {
        "confidenceRange95Percent": {
            "max": 19.2,
            "min": 12.27
        },
        "standardDeviation": 5.59,
        "unit": "g",
        "value": 16.0
    },
    "protein": {
        "confidenceRange95Percent": {
            "max": 29.31,
            "min": 8.12
        },
        "standardDeviation": 17.09,
        "unit": "g",
        "value": 13.0
    },
    "recipesUsed": 10
}

Quotas

Autocomplete Menu Item Search

Generate suggestions for menu items based on a (partial) query. The matches will be found by looking in the title only.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "results": [
        {
            "id": 253419,
            "title": "pei wei asian diner thai chicken lettuce wraps"
        },
        {
            "id": 380722,
            "title": "camille's chicken caesar salad includes 2 oz. caesar dressing"
        }
    ]
}

Quotas

Search Menu Items

Search over 115,000 menu items from over 800 fast food and chain restaurants. For example, McDonald's Big Mac or Starbucks Mocha.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "menuItems": [
        {
            "id": 419357,
            "title": "Burger Sliders",
            "restaurantChain": "Hooters",
            "image": "https://img.spoonacular.com/menu-items/419357-312x231.png",
            "imageType": "png",
            "servings": {
                "number": 1,
                "size": 2,
                "unit": "oz"
            }
        },
        {
            "id": 424571,
            "title": "Bacon King Burger",
            "restaurantChain": "Burger King",
            "image": "https://img.spoonacular.com/menu-items/424571-312x231.png",
            "imageType": "png",
            "servings": {
                "number": 1,
                "size": 2,
                "unit": "oz"
            }
        }
    ],
    "totalMenuItems": 6749,
    "type": "menuItem",
    "offset": 0,
    "number": 2
}

Quotas

Menu Item Nutrition Label Widget

Visualize a menu item's nutritional label information as HTML including CSS.

Headers

Request Headers:

• Accept: text/html

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The response will be an HTML widget that may look like this:

Quotas

Menu Item Nutrition Label Image

Visualize a menu item's nutritional label information as an image.

Headers

Request Headers:

• Accept: image/png

Response Headers:

• Content-Type: image/png

Parameters

The response will be an image that may look like this:

Quotas

Menu Item Nutrition by ID Widget

Visualize a menu item's nutritional information as HTML including CSS.

Headers

Request Headers:

• Accept: text/html

Response Headers:

• Content-Type: text/html

Parameters

/* HTML response */

The API response will be HTML and could look like this, for example:

Quotas

Menu Item Nutrition by ID Image

Visualize a menu item's nutritional information as HTML including CSS.

Headers

Request Headers:

• Accept: image/png

Response Headers:

• Content-Type: image/png

Parameters

The response will be an image that may look like this:

Quotas

Get Menu Item Information

Use a menu item id to get all available information about a menu item, such as nutrition.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "id": 424571,
    "title": "Bacon King Burger",
    "restaurantChain": "Burger King",
    "nutrition": {
        "nutrients": [
            {
                "name": "Fat",
                "amount": 69,
                "unit": "g",
                "percentOfDailyNeeds": 30
            },
            {
                "name": "Protein",
                "amount": 57,
                "unit": "g",
                "percentOfDailyNeeds": 35
            },
            {
                "name": "Calories",
                "amount": 1040,
                "unit": "cal",
                "percentOfDailyNeeds": 50
            },
            {
                "name": "Carbohydrates",
                "amount": 48,
                "unit": "g",
                "percentOfDailyNeeds": 35
            }
        ],
        "caloricBreakdown": {
            "percentProtein": 35,
            "percentFat": 30,
            "percentCarbs": 35
        }
    },
    "badges": [],
    "breadcrumbs": [
        "burger",
        "main course",
        "food product category"
    ],
    "generatedText": null,
    "imageType": "png",
    "likes": 0,
    "servings": {
        "number": 1,
        "size": 2,
        "unit": "oz"
    },
    "price": null,
    "spoonacularScore": null
}

Quotas

Generate Meal Plan

Generate a meal plan with three meals per day (breakfast, lunch, and dinner).

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "meals": [
        {
            "id": 655219,
            "title": "Peanut Butter And Chocolate Oatmeal",
            "imageType": "jpg",
            "readyInMinutes": 45,
            "servings": 1,
            "sourceUrl": "https://spoonacular.com/recipes/peanut-butter-and-chocolate-oatmeal-655219"
        },
        {
            "id": 649931,
            "title": "Lentil Salad With Vegetables",
            "imageType": "jpg",
            "readyInMinutes": 45,
            "servings": 4,
            "sourceUrl": "https://spoonacular.com/recipes/lentil-salad-with-vegetables-649931"
        },
        {
            "id": 632854,
            "title": "Asian Noodles",
            "imageType": "jpg",
            "readyInMinutes": 45,
            "servings": 4,
            "sourceUrl": "https://spoonacular.com/recipes/asian-noodles-632854"
        }
    ],
    "nutrients": {
        "calories": 1735.81,
        "carbohydrates": 235.17,
        "fat": 69.22,
        "protein": 55.43
    }
}

Quotas

Get Meal Plan Week

Retrieve a meal planned week for the given user. The username must be a spoonacular user and the hash must the the user's hash that can be found in his/her account.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "days": [
        {
            "nutritionSummary": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 310,
                        "unit": "cal",
                        "percentOfDailyNeeds": 16
                    },
                    {
                        "name": "Fat",
                        "amount": 25,
                        "unit": "g",
                        "percentOfDailyNeeds": 38
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 1,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Protein",
                        "amount": 20,
                        "unit": "g",
                        "percentOfDailyNeeds": 40
                    }
                ]
            },
            "nutritionSummaryBreakfast": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 0,
                        "unit": "cal",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Fat",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Protein",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    }
                ]
            },
            "nutritionSummaryLunch": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 310,
                        "unit": "cal",
                        "percentOfDailyNeeds": 16
                    },
                    {
                        "name": "Fat",
                        "amount": 25,
                        "unit": "g",
                        "percentOfDailyNeeds": 38
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 1,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Protein",
                        "amount": 20,
                        "unit": "g",
                        "percentOfDailyNeeds": 40
                    }
                ]
            },
            "nutritionSummaryDinner": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 0,
                        "unit": "cal",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Fat",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Protein",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    }
                ]
            },
            "date": 1589155200,
            "day": "Monday",
            "items": [
                {
                    "id": 1976489,
                    "slot": 1,
                    "position": 1,
                    "type": "RECIPE",
                    "value": {
                        "servings": 2,
                        "id": 1023004,
                        "title": "Foolproof Meatloaf",
                        "imageType": ""
                    }
                },
                {
                    "id": 1976490,
                    "slot": 2,
                    "position": 2,
                    "type": "CUSTOM_FOOD",
                    "value": {
                        "servings": 1,
                        "id": 345,
                        "title": "Denn's Lamb Bratwurst - 1/2 Pkg",
                        "image": "https://img.spoonacular.com/ingredients_100x100/bratwurst.jpg"
                    }
                }
            ]
        },
        {
            "nutritionSummary": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 200,
                        "unit": "cal",
                        "percentOfDailyNeeds": 10
                    },
                    {
                        "name": "Fat",
                        "amount": 1,
                        "unit": "g",
                        "percentOfDailyNeeds": 1
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 52,
                        "unit": "g",
                        "percentOfDailyNeeds": 17
                    },
                    {
                        "name": "Protein",
                        "amount": 2,
                        "unit": "g",
                        "percentOfDailyNeeds": 4
                    }
                ]
            },
            "nutritionSummaryBreakfast": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 200,
                        "unit": "cal",
                        "percentOfDailyNeeds": 10
                    },
                    {
                        "name": "Fat",
                        "amount": 1,
                        "unit": "g",
                        "percentOfDailyNeeds": 1
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 52,
                        "unit": "g",
                        "percentOfDailyNeeds": 17
                    },
                    {
                        "name": "Protein",
                        "amount": 2,
                        "unit": "g",
                        "percentOfDailyNeeds": 4
                    }
                ]
            },
            "nutritionSummaryLunch": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 0,
                        "unit": "cal",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Fat",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Protein",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    }
                ]
            },
            "nutritionSummaryDinner": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 0,
                        "unit": "cal",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Fat",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Protein",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    }
                ]
            },
            "date": 1589241600,
            "day": "Tuesday",
            "items": [
                {
                    "id": 1976491,
                    "slot": 1,
                    "position": 3,
                    "type": "INGREDIENTS",
                    "value": {
                        "title": "",
                        "servings": 1,
                        "ingredients": [
                            {
                                "name": "apple",
                                "unit": "",
                                "amount": "1",
                                "image": "https://img.spoonacular.com/ingredients_100x100/apple.jpg"
                            },
                            {
                                "name": "banana",
                                "unit": "",
                                "amount": "1",
                                "image": "https://img.spoonacular.com/ingredients_100x100/bananas.jpg"
                            }
                        ]
                    }
                }
            ]
        },
        {
            "nutritionSummary": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 180,
                        "unit": "cal",
                        "percentOfDailyNeeds": 9
                    },
                    {
                        "name": "Fat",
                        "amount": 6,
                        "unit": "g",
                        "percentOfDailyNeeds": 9
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 22,
                        "unit": "g",
                        "percentOfDailyNeeds": 7
                    },
                    {
                        "name": "Protein",
                        "amount": 10,
                        "unit": "g",
                        "percentOfDailyNeeds": 20
                    }
                ]
            },
            "nutritionSummaryBreakfast": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 180,
                        "unit": "cal",
                        "percentOfDailyNeeds": 9
                    },
                    {
                        "name": "Fat",
                        "amount": 6,
                        "unit": "g",
                        "percentOfDailyNeeds": 9
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 22,
                        "unit": "g",
                        "percentOfDailyNeeds": 7
                    },
                    {
                        "name": "Protein",
                        "amount": 10,
                        "unit": "g",
                        "percentOfDailyNeeds": 20
                    }
                ]
            },
            "nutritionSummaryLunch": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 0,
                        "unit": "cal",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Fat",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Protein",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    }
                ]
            },
            "nutritionSummaryDinner": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 0,
                        "unit": "cal",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Fat",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Protein",
                        "amount": 0,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    }
                ]
            },
            "date": 1589328000,
            "day": "Wednesday",
            "items": [
                {
                    "id": 1976492,
                    "slot": 1,
                    "position": 4,
                    "type": "MENU_ITEM",
                    "value": {
                        "servings": 1,
                        "id": 378557,
                        "title": "BBQ Steak Pizza, 9",
                        "image": "https://img.spoonacular.com/menu-items/378557-312x231.png",
                        "imageType": "png"
                    }
                }
            ]
        }
    ]
}

Quotas

Get Meal Plan Day

Retrieve a meal planned day for the given user. The username must be a spoonacular user and the hash must the the user's hash that can be found in his/her account.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "nutritionSummary": {
        "nutrients": [
            {
                "name": "Calories",
                "amount": 310,
                "unit": "cal",
                "percentOfDailyNeeds": 16
            },
            {
                "name": "Fat",
                "amount": 25,
                "unit": "g",
                "percentOfDailyNeeds": 38
            },
            {
                "name": "Carbohydrates",
                "amount": 1,
                "unit": "g",
                "percentOfDailyNeeds": 0
            },
            {
                "name": "Protein",
                "amount": 20,
                "unit": "g",
                "percentOfDailyNeeds": 40
            }
        ]
    },
    "nutritionSummaryBreakfast": {
        "nutrients": [
            {
                "name": "Calories",
                "amount": 0,
                "unit": "cal",
                "percentOfDailyNeeds": 0
            },
            {
                "name": "Fat",
                "amount": 0,
                "unit": "g",
                "percentOfDailyNeeds": 0
            },
            {
                "name": "Carbohydrates",
                "amount": 0,
                "unit": "g",
                "percentOfDailyNeeds": 0
            },
            {
                "name": "Protein",
                "amount": 0,
                "unit": "g",
                "percentOfDailyNeeds": 0
            }
        ]
    },
    "nutritionSummaryLunch": {
        "nutrients": [
            {
                "name": "Calories",
                "amount": 310,
                "unit": "cal",
                "percentOfDailyNeeds": 16
            },
            {
                "name": "Fat",
                "amount": 25,
                "unit": "g",
                "percentOfDailyNeeds": 38
            },
            {
                "name": "Carbohydrates",
                "amount": 1,
                "unit": "g",
                "percentOfDailyNeeds": 0
            },
            {
                "name": "Protein",
                "amount": 20,
                "unit": "g",
                "percentOfDailyNeeds": 40
            }
        ]
    },
    "nutritionSummaryDinner": {
        "nutrients": [
            {
                "name": "Calories",
                "amount": 0,
                "unit": "cal",
                "percentOfDailyNeeds": 0
            },
            {
                "name": "Fat",
                "amount": 0,
                "unit": "g",
                "percentOfDailyNeeds": 0
            },
            {
                "name": "Carbohydrates",
                "amount": 0,
                "unit": "g",
                "percentOfDailyNeeds": 0
            },
            {
                "name": "Protein",
                "amount": 0,
                "unit": "g",
                "percentOfDailyNeeds": 0
            }
        ]
    },
    "date": 1589155200,
    "day": "Monday",
    "items": [
        {
            "id": 1976489,
            "slot": 1,
            "position": 1,
            "type": "RECIPE",
            "value": {
                "servings": 2,
                "id": 1023004,
                "title": "Foolproof Meatloaf",
                "imageType": ""
            }
        },
        {
            "id": 1976490,
            "slot": 2,
            "position": 2,
            "type": "CUSTOM_FOOD",
            "value": {
                "servings": 1,
                "id": 345,
                "title": "Denn's Lamb Bratwurst - 1/2 Pkg",
                "image": "https://img.spoonacular.com/ingredients_100x100/bratwurst.jpg"
            }
        }
    ]
}

Quotas

Add to Meal Plan

Add an item to the user's meal plan.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "date": 1589500800,
    "slot": 1,
    "position": 0,
    "type": "INGREDIENTS",
    "value": {
        "ingredients": [
            {
                "name": "1 banana"
            }
        ]
    }
}

The field date is the timestamp of the day the item should be added to.

The field slot is either 1, 2, or 3 for breakfast, lunch, or dinner respectively.

The field position is the order in the slot.

The field type is either INGREDIENTS for simple foods such as "1 banana", PRODUCT for a grocery product, MENU_ITEM for a menu item, RECIPE for a recipe, or CUSTOM_FOOD for custom food.

The field value is information about the item and the structure depends on what type is set to. The example above shows what it would look like for type ingredient. If the type is PRODUCT, MENU_ITEM, or RECIPE the value must contain the field servings and the id of the respective item.

Example for adding a recipe with type RECIPE.

{
    "date": 1589500800,
    "slot": 1,
    "position": 0,
    "type": "RECIPE",
    "value": {
        "id": 296213,
        "servings": 2,
        "title": "Spinach Salad with Roasted Vegetables and Spiced Chickpea",
        "imageType": "jpg",
    }
}

Example for adding a grocery product with type PRODUCT.

{
    "date": 1589500800,
    "slot": 1,
    "position": 0,
    "type": "PRODUCT",
    "value": {
        "id": 183433,
        "servings": 1,
        "title": "Ahold Lasagna with Meat Sauce",
        "imageType": "jpg"
    }
}

Example for adding a menu item with type MENU_ITEM.

{
    "date": 1589500800,
    "slot": 1,
    "position": 0,
    "type": "MENU_ITEM",
    "value": {
        "id": 378557,
        "servings": 1,
        "title": "Pizza 73 BBQ Steak Pizza, 9",
        "imageType": "png"
    }
}

Example for adding a custom food with type CUSTOM_FOOD.

{
    "date": 1589500800,
    "slot": 1,
    "position": 0,
    "type": "CUSTOM_FOOD",
    "value": {
        "id": 348,
        "servings": 1,
        "title": "Aldi Spicy Cashews - 30g",
        "image": "https://img.spoonacular.com/ingredients_100x100/cashews.jpg"
    }
}

Example for adding simple foods with type INGREDIENTS. You can either just pass a name with amount and unit or pass a more complex object with amount, name, and unit in separate fields (recommended).

{
    "date": 1589500800,
    "slot": 1,
    "position": 0,
    "type": "INGREDIENTS",
    "value": {
        "ingredients": [
            {
                "name": "1 banana"
            },
            {
                "name": "coffee",
                "unit": "cup",
                "amount": "1",
                "image": "https://img.spoonacular.com/ingredients_100x100/brewed-coffee.jpg"
            },
        ]
    }
}

Alternatively you can add all items of a meal plan template to a user's meal plan with one call. Just pass the mealPlanTemplateId and the startDate in your request. The user's meal plan will be filled with template items starting on startDate (day 1 of the specified meal plan template).

{
    "mealPlanTemplateId": 120,
  	"startDate": 1596575356,    
}

You can also add multiple items with one request. Just pass a JSON Array with multiple items. See below for an example.

[
    {
        "date": 1589500800,
        "slot": 1,
        "position": 0,
        "type": "INGREDIENTS",
        "value": {
            "ingredients": [
                {
                    "name": "1 banana"
                },
                {
                    "name": "coffee",
                    "unit": "cup",
                    "amount": "1",
                    "image": "https://img.spoonacular.com/ingredients_100x100/brewed-coffee.jpg"
                },
            ]
        }
    },
    {
        "date": 1589500800,
        "slot": 2,
        "position": 0,
        "type": "CUSTOM_FOOD",
        "value": {
            "id": 348,
            "servings": 1,
            "title": "Aldi Spicy Cashews - 30g",
            "image": "https://img.spoonacular.com/ingredients_100x100/cashews.jpg"
        }
    }
]

Quotas

Clear Meal Plan Day

Delete all planned items from the user's meal plan for a specific day.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

Quotas

Delete from Meal Plan

Delete an item from the user's meal plan.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

Quotas

Get Meal Plan Templates

Get meal plan templates from user or public ones.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

Get user's templates.

{
    "templates": [
        {
            "id": 37,
            "name": "Busy Work Week"
        },
        {
            "id": 480,
            "name": "Keto Meal Plan"
        },
        {
            "id": 120,
            "name": "Not-So-Strict Paleo Meal Plan"
        },
        {
            "id": 451,
            "name": "Week 1 Meal Plan"
        },
        {
            "id": 581,
            "name": "Whole30 Meal Plan"
        }
    ]
}

Get public templates.

{
    "templates": [
        {
            "id": 37,
            "name": "Busy Work Week"
        },
        {
            "id": 480,
            "name": "Keto Meal Plan"
        },
        {
            "id": 120,
            "name": "Not-So-Strict Paleo Meal Plan"
        },
        {
            "id": 451,
            "name": "Week 1 Meal Plan"
        },
        {
            "id": 581,
            "name": "Whole30 Meal Plan"
        }
    ]
}

Quotas

Get Meal Plan Template

Get information about a meal plan template.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "id": 128,
    "name": "1500 Calorie Meal Plan",
    "days": [
        {
            "nutritionSummary": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 1293,
                        "unit": "cal",
                        "percentOfDailyNeeds": 65
                    },
                    {
                        "name": "Fat",
                        "amount": 65,
                        "unit": "g",
                        "percentOfDailyNeeds": 100
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 102,
                        "unit": "g",
                        "percentOfDailyNeeds": 34
                    },
                    {
                        "name": "Protein",
                        "amount": 83,
                        "unit": "g",
                        "percentOfDailyNeeds": 166
                    }
                ]
            },
            "nutritionSummaryBreakfast": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 132,
                        "unit": "cal",
                        "percentOfDailyNeeds": 7
                    },
                    {
                        "name": "Fat",
                        "amount": 3,
                        "unit": "g",
                        "percentOfDailyNeeds": 4
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 25,
                        "unit": "g",
                        "percentOfDailyNeeds": 8
                    },
                    {
                        "name": "Protein",
                        "amount": 3,
                        "unit": "g",
                        "percentOfDailyNeeds": 5
                    }
                ]
            },
            "nutritionSummaryLunch": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 455,
                        "unit": "cal",
                        "percentOfDailyNeeds": 23
                    },
                    {
                        "name": "Fat",
                        "amount": 34,
                        "unit": "g",
                        "percentOfDailyNeeds": 52
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 1,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Protein",
                        "amount": 35,
                        "unit": "g",
                        "percentOfDailyNeeds": 70
                    }
                ]
            },
            "nutritionSummaryDinner": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 706,
                        "unit": "cal",
                        "percentOfDailyNeeds": 35
                    },
                    {
                        "name": "Fat",
                        "amount": 29,
                        "unit": "g",
                        "percentOfDailyNeeds": 45
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 76,
                        "unit": "g",
                        "percentOfDailyNeeds": 25
                    },
                    {
                        "name": "Protein",
                        "amount": 46,
                        "unit": "g",
                        "percentOfDailyNeeds": 91
                    }
                ]
            },
            "day": "1",
            "items": [
                {
                    "id": 2403,
                    "slot": 1,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 630657,
                        "title": "Double Chocolate Protein Cookies",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2404,
                    "slot": 1,
                    "position": 0,
                    "type": "INGREDIENTS",
                    "value": {
                        "name": "",
                        "servings": "1",
                        "ingredients": [
                            {
                                "name": "orange",
                                "image": "https://img.spoonacular.com/ingredients_100x100/orange.jpg",
                                "amount": 1,
                                "unit": ""
                            }
                        ]
                    }
                },
                {
                    "id": 2405,
                    "slot": 2,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 296213,
                        "title": "Spinach Salad with Roasted Vegetables and Spiced Chickpea",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2406,
                    "slot": 3,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 237677,
                        "title": "Chicken Parmesan with Spaghetti",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2407,
                    "slot": 3,
                    "position": 0,
                    "type": "INGREDIENTS",
                    "value": {
                        "name": "",
                        "servings": "1",
                        "ingredients": [
                            {
                                "name": "broccoli",
                                "image": "https://img.spoonacular.com/ingredients_100x100/broccoli.jpg",
                                "amount": 1,
                                "unit": "cup"
                            }
                        ]
                    }
                },
                {
                    "id": 2408,
                    "slot": 3,
                    "position": 0,
                    "type": "PRODUCT",
                    "value": {
                        "id": 146191,
                        "title": "Lindt Dark Chocolate",
                        "imageType": "jpg"
                    }
                }
            ]
        },
        {
            "nutritionSummary": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 1386,
                        "unit": "cal",
                        "percentOfDailyNeeds": 69
                    },
                    {
                        "name": "Fat",
                        "amount": 66,
                        "unit": "g",
                        "percentOfDailyNeeds": 102
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 162,
                        "unit": "g",
                        "percentOfDailyNeeds": 54
                    },
                    {
                        "name": "Protein",
                        "amount": 48,
                        "unit": "g",
                        "percentOfDailyNeeds": 96
                    }
                ]
            },
            "nutritionSummaryBreakfast": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 239,
                        "unit": "cal",
                        "percentOfDailyNeeds": 12
                    },
                    {
                        "name": "Fat",
                        "amount": 11,
                        "unit": "g",
                        "percentOfDailyNeeds": 17
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 34,
                        "unit": "g",
                        "percentOfDailyNeeds": 11
                    },
                    {
                        "name": "Protein",
                        "amount": 5,
                        "unit": "g",
                        "percentOfDailyNeeds": 9
                    }
                ]
            },
            "nutritionSummaryLunch": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 732,
                        "unit": "cal",
                        "percentOfDailyNeeds": 37
                    },
                    {
                        "name": "Fat",
                        "amount": 33,
                        "unit": "g",
                        "percentOfDailyNeeds": 51
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 91,
                        "unit": "g",
                        "percentOfDailyNeeds": 30
                    },
                    {
                        "name": "Protein",
                        "amount": 22,
                        "unit": "g",
                        "percentOfDailyNeeds": 44
                    }
                ]
            },
            "nutritionSummaryDinner": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 414,
                        "unit": "cal",
                        "percentOfDailyNeeds": 21
                    },
                    {
                        "name": "Fat",
                        "amount": 22,
                        "unit": "g",
                        "percentOfDailyNeeds": 33
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 37,
                        "unit": "g",
                        "percentOfDailyNeeds": 12
                    },
                    {
                        "name": "Protein",
                        "amount": 21,
                        "unit": "g",
                        "percentOfDailyNeeds": 43
                    }
                ]
            },
            "day": "2",
            "items": [
                {
                    "id": 2409,
                    "slot": 1,
                    "position": 0,
                    "type": "PRODUCT",
                    "value": {
                        "id": 101999,
                        "title": "Greek Gods Yogurt",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2410,
                    "slot": 1,
                    "position": 0,
                    "type": "INGREDIENTS",
                    "value": {
                        "name": "",
                        "servings": "1",
                        "ingredients": [
                            {
                                "name": "berries",
                                "image": "https://img.spoonacular.com/ingredients_100x100/berries-mixed.jpg",
                                "amount": 1,
                                "unit": "cup"
                            }
                        ]
                    }
                },
                {
                    "id": 2411,
                    "slot": 2,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 516377,
                        "title": "Southwest Quinoa Salad",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2412,
                    "slot": 3,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 247683,
                        "title": "Pesto Caprese Omelette",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2413,
                    "slot": 3,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 484337,
                        "title": "One Ingredient Banana Ice Cream",
                        "imageType": "jpg"
                    }
                }
            ]
        },
        {
            "nutritionSummary": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 1589,
                        "unit": "cal",
                        "percentOfDailyNeeds": 79
                    },
                    {
                        "name": "Fat",
                        "amount": 77,
                        "unit": "g",
                        "percentOfDailyNeeds": 118
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 158,
                        "unit": "g",
                        "percentOfDailyNeeds": 53
                    },
                    {
                        "name": "Protein",
                        "amount": 84,
                        "unit": "g",
                        "percentOfDailyNeeds": 168
                    }
                ]
            },
            "nutritionSummaryBreakfast": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 472,
                        "unit": "cal",
                        "percentOfDailyNeeds": 24
                    },
                    {
                        "name": "Fat",
                        "amount": 14,
                        "unit": "g",
                        "percentOfDailyNeeds": 21
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 62,
                        "unit": "g",
                        "percentOfDailyNeeds": 21
                    },
                    {
                        "name": "Protein",
                        "amount": 27,
                        "unit": "g",
                        "percentOfDailyNeeds": 54
                    }
                ]
            },
            "nutritionSummaryLunch": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 568,
                        "unit": "cal",
                        "percentOfDailyNeeds": 28
                    },
                    {
                        "name": "Fat",
                        "amount": 45,
                        "unit": "g",
                        "percentOfDailyNeeds": 69
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 31,
                        "unit": "g",
                        "percentOfDailyNeeds": 10
                    },
                    {
                        "name": "Protein",
                        "amount": 18,
                        "unit": "g",
                        "percentOfDailyNeeds": 36
                    }
                ]
            },
            "nutritionSummaryDinner": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 549,
                        "unit": "cal",
                        "percentOfDailyNeeds": 27
                    },
                    {
                        "name": "Fat",
                        "amount": 18,
                        "unit": "g",
                        "percentOfDailyNeeds": 27
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 65,
                        "unit": "g",
                        "percentOfDailyNeeds": 22
                    },
                    {
                        "name": "Protein",
                        "amount": 39,
                        "unit": "g",
                        "percentOfDailyNeeds": 78
                    }
                ]
            },
            "day": "3",
            "items": [
                {
                    "id": 2414,
                    "slot": 1,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 157259,
                        "title": "Cocoa Protein Pancakes",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2415,
                    "slot": 1,
                    "position": 0,
                    "type": "INGREDIENTS",
                    "value": {
                        "name": "",
                        "servings": "1",
                        "ingredients": [
                            {
                                "name": "orange",
                                "image": "https://img.spoonacular.com/ingredients_100x100/orange.jpg",
                                "amount": 1,
                                "unit": ""
                            }
                        ]
                    }
                },
                {
                    "id": 2416,
                    "slot": 2,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 535856,
                        "title": "BLT Chopped Salad",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2417,
                    "slot": 2,
                    "position": 0,
                    "type": "PRODUCT",
                    "value": {
                        "id": 71144,
                        "title": "Kind Plus Fruit & Nut Bar - Almond Walnut Macadamia with Peanuts Plus Protein",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2418,
                    "slot": 3,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 519197,
                        "title": "Zesty Sriracha Shrimp and Quinoa",
                        "imageType": "png"
                    }
                },
                {
                    "id": 2419,
                    "slot": 3,
                    "position": 0,
                    "type": "PRODUCT",
                    "value": {
                        "id": 163427,
                        "title": "Green Giant Valley Fresh Steamers - Select Sugar Snap Peas",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2420,
                    "slot": 3,
                    "position": 0,
                    "type": "PRODUCT",
                    "value": {
                        "id": 146191,
                        "title": "Lindt Dark Chocolate",
                        "imageType": "jpg"
                    }
                }
            ]
        },
        {
            "nutritionSummary": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 1343,
                        "unit": "cal",
                        "percentOfDailyNeeds": 67
                    },
                    {
                        "name": "Fat",
                        "amount": 70,
                        "unit": "g",
                        "percentOfDailyNeeds": 108
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 123,
                        "unit": "g",
                        "percentOfDailyNeeds": 41
                    },
                    {
                        "name": "Protein",
                        "amount": 61,
                        "unit": "g",
                        "percentOfDailyNeeds": 122
                    }
                ]
            },
            "nutritionSummaryBreakfast": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 239,
                        "unit": "cal",
                        "percentOfDailyNeeds": 12
                    },
                    {
                        "name": "Fat",
                        "amount": 11,
                        "unit": "g",
                        "percentOfDailyNeeds": 17
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 34,
                        "unit": "g",
                        "percentOfDailyNeeds": 11
                    },
                    {
                        "name": "Protein",
                        "amount": 5,
                        "unit": "g",
                        "percentOfDailyNeeds": 9
                    }
                ]
            },
            "nutritionSummaryLunch": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 406,
                        "unit": "cal",
                        "percentOfDailyNeeds": 20
                    },
                    {
                        "name": "Fat",
                        "amount": 17,
                        "unit": "g",
                        "percentOfDailyNeeds": 26
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 56,
                        "unit": "g",
                        "percentOfDailyNeeds": 19
                    },
                    {
                        "name": "Protein",
                        "amount": 10,
                        "unit": "g",
                        "percentOfDailyNeeds": 21
                    }
                ]
            },
            "nutritionSummaryDinner": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 698,
                        "unit": "cal",
                        "percentOfDailyNeeds": 35
                    },
                    {
                        "name": "Fat",
                        "amount": 43,
                        "unit": "g",
                        "percentOfDailyNeeds": 66
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 34,
                        "unit": "g",
                        "percentOfDailyNeeds": 11
                    },
                    {
                        "name": "Protein",
                        "amount": 46,
                        "unit": "g",
                        "percentOfDailyNeeds": 92
                    }
                ]
            },
            "day": "4",
            "items": [
                {
                    "id": 2421,
                    "slot": 1,
                    "position": 0,
                    "type": "PRODUCT",
                    "value": {
                        "id": 101999,
                        "title": "Greek Gods Yogurt",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2422,
                    "slot": 1,
                    "position": 0,
                    "type": "INGREDIENTS",
                    "value": {
                        "name": "",
                        "servings": "1",
                        "ingredients": [
                            {
                                "name": "berries",
                                "image": "https://img.spoonacular.com/ingredients_100x100/berries-mixed.jpg",
                                "amount": 1,
                                "unit": "cup"
                            }
                        ]
                    }
                },
                {
                    "id": 2423,
                    "slot": 2,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 535563,
                        "title": "Black Bean Quinoa Salad",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2424,
                    "slot": 3,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 622598,
                        "title": "Pittata - Pizza Frittata",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2425,
                    "slot": 3,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 484337,
                        "title": "One Ingredient Banana Ice Cream",
                        "imageType": "jpg"
                    }
                }
            ]
        },
        {
            "nutritionSummary": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 1247,
                        "unit": "cal",
                        "percentOfDailyNeeds": 62
                    },
                    {
                        "name": "Fat",
                        "amount": 61,
                        "unit": "g",
                        "percentOfDailyNeeds": 95
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 103,
                        "unit": "g",
                        "percentOfDailyNeeds": 34
                    },
                    {
                        "name": "Protein",
                        "amount": 78,
                        "unit": "g",
                        "percentOfDailyNeeds": 156
                    }
                ]
            },
            "nutritionSummaryBreakfast": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 295,
                        "unit": "cal",
                        "percentOfDailyNeeds": 15
                    },
                    {
                        "name": "Fat",
                        "amount": 12,
                        "unit": "g",
                        "percentOfDailyNeeds": 19
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 42,
                        "unit": "g",
                        "percentOfDailyNeeds": 14
                    },
                    {
                        "name": "Protein",
                        "amount": 11,
                        "unit": "g",
                        "percentOfDailyNeeds": 23
                    }
                ]
            },
            "nutritionSummaryLunch": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 455,
                        "unit": "cal",
                        "percentOfDailyNeeds": 23
                    },
                    {
                        "name": "Fat",
                        "amount": 34,
                        "unit": "g",
                        "percentOfDailyNeeds": 52
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 1,
                        "unit": "g",
                        "percentOfDailyNeeds": 0
                    },
                    {
                        "name": "Protein",
                        "amount": 35,
                        "unit": "g",
                        "percentOfDailyNeeds": 70
                    }
                ]
            },
            "nutritionSummaryDinner": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 497,
                        "unit": "cal",
                        "percentOfDailyNeeds": 25
                    },
                    {
                        "name": "Fat",
                        "amount": 15,
                        "unit": "g",
                        "percentOfDailyNeeds": 24
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 60,
                        "unit": "g",
                        "percentOfDailyNeeds": 20
                    },
                    {
                        "name": "Protein",
                        "amount": 32,
                        "unit": "g",
                        "percentOfDailyNeeds": 63
                    }
                ]
            },
            "day": "5",
            "items": [
                {
                    "id": 2426,
                    "slot": 1,
                    "position": 0,
                    "type": "PRODUCT",
                    "value": {
                        "id": 71144,
                        "title": "Kind Plus Fruit & Nut Bar - Almond Walnut Macadamia with Peanuts Plus Protein",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2427,
                    "slot": 1,
                    "position": 0,
                    "type": "INGREDIENTS",
                    "value": {
                        "name": "",
                        "servings": "1",
                        "ingredients": [
                            {
                                "name": "banana",
                                "image": "https://img.spoonacular.com/ingredients_100x100/bananas.jpg",
                                "amount": 1,
                                "unit": ""
                            }
                        ]
                    }
                },
                {
                    "id": 2428,
                    "slot": 2,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 296213,
                        "title": "Spinach Salad with Roasted Vegetables and Spiced Chickpea",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2429,
                    "slot": 3,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 497301,
                        "title": "Shrimp Scampi",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2430,
                    "slot": 3,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 581021,
                        "title": "Black Bean Brownies: Fudgy Fun",
                        "imageType": "jpg"
                    }
                }
            ]
        },
        {
            "nutritionSummary": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 1683,
                        "unit": "cal",
                        "percentOfDailyNeeds": 84
                    },
                    {
                        "name": "Fat",
                        "amount": 68,
                        "unit": "g",
                        "percentOfDailyNeeds": 105
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 139,
                        "unit": "g",
                        "percentOfDailyNeeds": 46
                    },
                    {
                        "name": "Protein",
                        "amount": 106,
                        "unit": "g",
                        "percentOfDailyNeeds": 212
                    }
                ]
            },
            "nutritionSummaryBreakfast": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 490,
                        "unit": "cal",
                        "percentOfDailyNeeds": 24
                    },
                    {
                        "name": "Fat",
                        "amount": 15,
                        "unit": "g",
                        "percentOfDailyNeeds": 23
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 65,
                        "unit": "g",
                        "percentOfDailyNeeds": 22
                    },
                    {
                        "name": "Protein",
                        "amount": 26,
                        "unit": "g",
                        "percentOfDailyNeeds": 53
                    }
                ]
            },
            "nutritionSummaryLunch": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 378,
                        "unit": "cal",
                        "percentOfDailyNeeds": 19
                    },
                    {
                        "name": "Fat",
                        "amount": 33,
                        "unit": "g",
                        "percentOfDailyNeeds": 51
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 16,
                        "unit": "g",
                        "percentOfDailyNeeds": 5
                    },
                    {
                        "name": "Protein",
                        "amount": 8,
                        "unit": "g",
                        "percentOfDailyNeeds": 16
                    }
                ]
            },
            "nutritionSummaryDinner": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 816,
                        "unit": "cal",
                        "percentOfDailyNeeds": 41
                    },
                    {
                        "name": "Fat",
                        "amount": 21,
                        "unit": "g",
                        "percentOfDailyNeeds": 32
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 58,
                        "unit": "g",
                        "percentOfDailyNeeds": 19
                    },
                    {
                        "name": "Protein",
                        "amount": 72,
                        "unit": "g",
                        "percentOfDailyNeeds": 144
                    }
                ]
            },
            "day": "6",
            "items": [
                {
                    "id": 2431,
                    "slot": 1,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 157259,
                        "title": "Cocoa Protein Pancakes",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2432,
                    "slot": 1,
                    "position": 0,
                    "type": "INGREDIENTS",
                    "value": {
                        "name": "",
                        "servings": "1",
                        "ingredients": [
                            {
                                "name": "berries",
                                "image": "https://img.spoonacular.com/ingredients_100x100/berries-mixed.jpg",
                                "amount": 1,
                                "unit": "cup"
                            }
                        ]
                    }
                },
                {
                    "id": 2433,
                    "slot": 2,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 535856,
                        "title": "BLT Chopped Salad",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2434,
                    "slot": 3,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 149425,
                        "title": "Herb and Cheddar Cordon Bleu",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2435,
                    "slot": 3,
                    "position": 0,
                    "type": "INGREDIENTS",
                    "value": {
                        "name": "",
                        "servings": "1",
                        "ingredients": [
                            {
                                "name": "brussels sprouts",
                                "image": "https://img.spoonacular.com/ingredients_100x100/brussels-sprouts.jpg",
                                "amount": 1,
                                "unit": "cup"
                            }
                        ]
                    }
                },
                {
                    "id": 2436,
                    "slot": 3,
                    "position": 0,
                    "type": "INGREDIENTS",
                    "value": {
                        "name": "",
                        "servings": "1",
                        "ingredients": [
                            {
                                "name": "wine",
                                "image": "https://img.spoonacular.com/ingredients_100x100/white-wine.jpg",
                                "amount": 5,
                                "unit": "ounces"
                            }
                        ]
                    }
                }
            ]
        },
        {
            "nutritionSummary": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 1442,
                        "unit": "cal",
                        "percentOfDailyNeeds": 72
                    },
                    {
                        "name": "Fat",
                        "amount": 69,
                        "unit": "g",
                        "percentOfDailyNeeds": 106
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 147,
                        "unit": "g",
                        "percentOfDailyNeeds": 49
                    },
                    {
                        "name": "Protein",
                        "amount": 73,
                        "unit": "g",
                        "percentOfDailyNeeds": 147
                    }
                ]
            },
            "nutritionSummaryBreakfast": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 444,
                        "unit": "cal",
                        "percentOfDailyNeeds": 22
                    },
                    {
                        "name": "Fat",
                        "amount": 12,
                        "unit": "g",
                        "percentOfDailyNeeds": 19
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 51,
                        "unit": "g",
                        "percentOfDailyNeeds": 17
                    },
                    {
                        "name": "Protein",
                        "amount": 38,
                        "unit": "g",
                        "percentOfDailyNeeds": 76
                    }
                ]
            },
            "nutritionSummaryLunch": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 406,
                        "unit": "cal",
                        "percentOfDailyNeeds": 20
                    },
                    {
                        "name": "Fat",
                        "amount": 17,
                        "unit": "g",
                        "percentOfDailyNeeds": 26
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 56,
                        "unit": "g",
                        "percentOfDailyNeeds": 19
                    },
                    {
                        "name": "Protein",
                        "amount": 10,
                        "unit": "g",
                        "percentOfDailyNeeds": 21
                    }
                ]
            },
            "nutritionSummaryDinner": {
                "nutrients": [
                    {
                        "name": "Calories",
                        "amount": 593,
                        "unit": "cal",
                        "percentOfDailyNeeds": 30
                    },
                    {
                        "name": "Fat",
                        "amount": 40,
                        "unit": "g",
                        "percentOfDailyNeeds": 62
                    },
                    {
                        "name": "Carbohydrates",
                        "amount": 41,
                        "unit": "g",
                        "percentOfDailyNeeds": 14
                    },
                    {
                        "name": "Protein",
                        "amount": 25,
                        "unit": "g",
                        "percentOfDailyNeeds": 50
                    }
                ]
            },
            "day": "7",
            "items": [
                {
                    "id": 2437,
                    "slot": 1,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 619085,
                        "title": "Protein Packed Healthy French Toast with Chocolate and Peanut Butter {Super Simple, Whole Wheat}",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2438,
                    "slot": 1,
                    "position": 0,
                    "type": "INGREDIENTS",
                    "value": {
                        "name": "",
                        "servings": "1",
                        "ingredients": [
                            {
                                "name": "orange",
                                "image": "https://img.spoonacular.com/ingredients_100x100/orange.jpg",
                                "amount": 1,
                                "unit": ""
                            }
                        ]
                    }
                },
                {
                    "id": 2439,
                    "slot": 2,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 535563,
                        "title": "Black Bean Quinoa Salad",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2440,
                    "slot": 3,
                    "position": 0,
                    "type": "RECIPE",
                    "value": {
                        "id": 590570,
                        "title": "Asian Beef Lettuce Wraps",
                        "imageType": "jpg"
                    }
                },
                {
                    "id": 2441,
                    "slot": 3,
                    "position": 0,
                    "type": "PRODUCT",
                    "value": {
                        "id": 146191,
                        "title": "Lindt Dark Chocolate",
                        "imageType": "jpg"
                    }
                }
            ]
        }
    ]
}

Quotas

Add Meal Plan Template

Add a meal plan template for a user.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "name": "My new meal plan template",
    "items": [
        {
            "day": 1,
            "slot": 1,
            "position": 0,
            "type": "RECIPE",
            "value": {
                "id": 296213,
                "servings": 2,
                "title": "Spinach Salad with Roasted Vegetables and Spiced Chickpea",
                "imageType": "jpg"
            }
        },
        {
            "day": 2,
            "slot": 1,
            "position": 0,
            "type": "PRODUCT",
            "value": {
                "id": 183433,
                "servings": 1,
                "title": "Ahold Lasagna with Meat Sauce",
                "imageType": "jpg"
            }
        },
        {
            "day": 3,
            "slot": 1,
            "position": 0,
            "type": "MENU_ITEM",
            "value": {
                "id": 378557,
                "servings": 1,
                "title": "Pizza 73 BBQ Steak Pizza, 9",
                "imageType": "png"
            }
        },
        {
            "day": 4,
            "slot": 1,
            "position": 0,
            "type": "CUSTOM_FOOD",
            "value": {
                "id": 348,
                "servings": 1,
                "title": "Aldi Spicy Cashews - 30g",
                "image": "https://img.spoonacular.com/ingredients_100x100/cashews.jpg"
            }
        },
        {
            "day": 5,
            "slot": 1,
            "position": 0,
            "type": "INGREDIENTS",
            "value": {
                "ingredients": [
                    {
                        "name": "1 banana"
                    },
                    {
                        "name": "coffee",
                        "unit": "cup",
                        "amount": "1",
                        "image": "https://img.spoonacular.com/ingredients_100x100/brewed-coffee.jpg"
                    }
                ]
            }
        }
    ],
    "publishAsPublic": false
}

Quotas

Delete Meal Plan Template

Delete a meal plan template for a user.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "status": "success"
}

Quotas

Get Shopping List

Get the current shopping list for the given user.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "aisles": [
        {
            "aisle": "Baking",
            "items": [
                {
                    "id": 115388,
                    "name": "baking powder",
                    "measures": {
                        "original": {
                            "amount": 1.0,
                            "unit": "package"
                        },
                        "metric": {
                            "amount": 1.0,
                            "unit": "pkg"
                        },
                        "us": {
                            "amount": 1.0,
                            "unit": "pkg"
                        }
                    },
                    "pantryItem": false,
                    "aisle": "Baking",
                    "cost": 0.71,
                    "ingredientId": 18369
                }                
            ]
        }
    ],
    "cost": 1.43,
    "startDate": 1588291200,
    "endDate": 1588896000
}

Quotas

Generate Shopping List

Generate the shopping list for a user from the meal planner in a given time frame.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "aisles": [
        {
            "aisle": "Baking",
            "items": [
                {
                    "id": 115388,
                    "name": "baking powder",
                    "measures": {
                        "original": {
                            "amount": 1.0,
                            "unit": "package"
                        },
                        "metric": {
                            "amount": 1.0,
                            "unit": "pkg"
                        },
                        "us": {
                            "amount": 1.0,
                            "unit": "pkg"
                        }
                    },
                    "pantryItem": false,
                    "aisle": "Baking",
                    "cost": 0.71,
                    "ingredientId": 18369
                }                
            ]
        }
    ],
    "cost": 0.71,
    "startDate": 1588291200,
    "endDate": 1588896000
}

Quotas

Compute Shopping List

Compute a shopping list from a set of simple foods. This endpoint does not require usernames.

Headers

Response Headers:

• Content-Type: application/json

{
    "items": [
        "4 lbs tomatoes",
        "10 tomatoes",
        "20 Tablespoons Olive Oil",
        "6 tbsp Olive Oil"
    ]
}

{
    "aisles": [
        {
            "aisle": "Pantry Items",
            "items": [
                {
                    "name": "olive oil",
                    "measures": {
                        "metric": {
                            "amount": 364.0,
                            "unit": "ml"
                        },
                        "us": {
                            "amount": 12.4,
                            "unit": "fl oz"
                        }
                    },
                    "pantryItem": true,
                    "aisle": "Pantry Items",
                    "cost": 333.55,
                    "ingredientId": 4053
                }
            ]
        },
        {
            "aisle": "Produce",
            "items": [
                {
                    "name": "tomatoes",
                    "measures": {
                        "metric": {
                            "amount": 3044.4,
                            "unit": "g"
                        },
                        "us": {
                            "amount": 6.8,
                            "unit": "lb"
                        }
                    },
                    "pantryItem": false,
                    "aisle": "Produce",
                    "cost": 532.21,
                    "ingredientId": 11529
                }
            ]
        }
    ],
    "cost": 1326.62
}

Quotas

Connect User

In order to call user-specific endpoints, you need to connect your app's users to spoonacular users.

Just call this endpoint with your user's information and you will get back a username and hash that you must save on your side. In future requests that you make on this user's behalf you simply pass their username and hash alongside your API key.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "username": "your user's name",
    "firstName": "your user's first name",
    "lastName": "your user's last name",
    "email": "your user's email"
}

The response will give you the corresponding spoonacular usernamem, the password with which the user can log in to spoonacular.com, and the hash. Save this information permanently on your end and connect it with your user.

{
    "username": "api_123_user",
    "spoonacularPassword": "meadwith31grapejam",
    "hash": "q572587bq2405724q05"
}

Quotas

Add to Shopping List

Add an item to the current shopping list of a user.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
	"item": "1 package baking powder",
	"aisle": "Baking",
	"parse": true
}

The field aisle is optional and will be added if not given.

Set parse false if you want to put a non-food item to the shopping list.

{
    "aisles": [
        {
            "aisle": "Baking",
            "items": [
                {
                    "id": 115388,
                    "name": "baking powder",
                    "measures": {
                        "original": {
                            "amount": 1.0,
                            "unit": "package"
                        },
                        "metric": {
                            "amount": 1.0,
                            "unit": "pkg"
                        },
                        "us": {
                            "amount": 1.0,
                            "unit": "pkg"
                        }
                    },
                    "pantryItem": false,
                    "aisle": "Baking",
                    "cost": 0.71,
                    "ingredientId": 18369
                }                
            ]
        }
    ],
    "cost": 0.71,
    "startDate": 1588291200,
    "endDate": 1588896000
}

Quotas

Delete from Shopping List

Delete an item from the current shopping list of the user.

Read more about working with the meal planner.

Headers

Response Headers:

• Content-Type: application/json

Parameters

Quotas

Dish Pairing for Wine

Find a dish that goes well with a given wine.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "pairings": [
        "stew",
        "steak",
        "chili",
        "burger"
    ],
    "text": "Malbec is a dry red wine which is bold and full bodied. It goes especially well with round steak, tri tip steak, steak, boneless pork chops, and pizza burger."
}

Quotas

Wine Pairing

Find a wine that goes well with a food. Food can be a dish name ("steak"), an ingredient name ("salmon"), or a cuisine ("italian").

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "pairedWines": [
        "merlot",
        "cabernet sauvignon",
        "pinot noir"
    ],
    "pairingText": "Merlot, Cabernet Sauvignon, and Pinot Noir are my top picks for Steak. After all, beef and red wine are a classic combination. Generally, leaner steaks go well with light or medium-bodied reds, such as pinot noir or merlot, while fattier steaks can handle a bold red, such as cabernet sauvingnon. The Sterling Vineyards Merlot with a 5 out of 5 star rating seems like a good match. It costs about 29 dollars per bottle.",
    "productMatches": [
        {
            "id": 428278,
            "title": "Sterling Vineyards Merlot",
            "averageRating": 1.0,
            "description": null,
            "imageUrl": "https://img.spoonacular.com/products/428278-312x231.jpg",
            "link": "https://www.amazon.com/2014-Sterling-Vineyards-Valley-Merlot/dp/B071FP8NPG?tag=spoonacular-20",
            "price": "$28.99",
            "ratingCount": 1.0,
            "score": 0.75
        }
    ]
}

Quotas

Wine Description

Get a simple description of a certain wine, e.g. "malbec", "riesling", or "merlot".

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "wineDescription": "Merlot is a dry red wine which is smooth and medium bodied."
}

Quotas

Wine Recommendation

Get a specific wine recommendation (concrete product) for a given wine type, e.g. "merlot".

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "recommendedWines": [
        {
            "id": 447938,
            "title": "Rombauer Merlot",
            "averageRating": 0.96,
            "description": "Enticing and lively red color; beautifully aromatic with black cherry and ripe plum. On the palate a purity of blackcurrant, cedar and mint flavors blend together seamlessly. Soft and supple, this wine has a medium-bodied mouth-feel with plush tannins that integrate with the generous finish.Our favorite pairings for this wine include chicken parmesan, cedar-planked salmon over wild rice, and mushroom pizza.",
            "imageUrl": "https://img.spoonacular.com/products/447938-312x231.jpg",
            "link": "https://click.linksynergy.com/deeplink?id=*QCiIS6t4gA&mid=2025&murl=https%3A%2F%2Fwww.wine.com%2Fproduct%2Frombauer-merlot-2008%2F116883",
            "price": "$25.59",
            "ratingCount": 5.0,
            "score": 0.8975
        },
        {
            "id": 430475,
            "title": "NV The Big Kahuna Merlot",
            "averageRating": 0.9,
            "description": "A ripe and rounded Merlot with notes of plum, blackberry, and hint of spice.",
            "imageUrl": "https://img.spoonacular.com/products/430475-312x231.jpg",
            "link": "https://www.amazon.com/Big-Kahuna-Merlot-Red-Wine/dp/B01F5XPTUW?tag=spoonacular-20",
            "price": "$6.99",
            "ratingCount": 4.0,
            "score": 0.823076923076923
        }
    ],
    "totalFound": 21
}

Quotas

Image Classification by File

Classify a food image. You can play around with that endpoint!

See here for a full list of supported categories.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "category": "burger",
    "probability": 0.91354
}

Quotas

Image Classification by URL

Classify a food image. You can play around with that endpoint!

See here for a full list of supported categories.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "category": "burger",
    "probability": 0.91354
}

Quotas

Image Analysis by File

Analyze a food image. The API tries to classify the image, guess the nutrition, and find a matching recipes. You can play around with that endpoint!

See here for a full list of supported categories.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
  "nutrition": {
    "recipesUsed": 25,
    "calories": {
      "value": 508,
      "unit": "calories",
      "confidenceRange95Percent": {
        "min": 428.97,
        "max": 571.98
      },
      "standardDeviation": 182.4
    },
    "fat": {
      "value": 21,
      "unit": "g",
      "confidenceRange95Percent": {
        "min": 21.29,
        "max": 32.95
      },
      "standardDeviation": 14.88
    },
    "protein": {
      "value": 29,
      "unit": "g",
      "confidenceRange95Percent": {
        "min": 22.58,
        "max": 33.7
      },
      "standardDeviation": 14.19
    },
    "carbs": {
      "value": 40,
      "unit": "g",
      "confidenceRange95Percent": {
        "min": 29.74,
        "max": 44.96
      },
      "standardDeviation": 19.42
    }
  },
  "category": {
    "name": "burger",
    "probability": 0.99
  },
  "recipes": [
    {
      "id": 477749,
      "title": "Burger Club: Award-Winning Logan County Burger Patty Melt",
      "imageType": "jpg",
      "sourceUrl": "http://www.barbarabakes.com/2010/05/burger-club-award-winning-logan-county/"
    },
    {
      "id": 493632,
      "title": "New York Burger Week: Pretzel Burger with Beer Cheese",
      "imageType": "jpg",
      "sourceUrl": "http://www.foodrepublic.com/2013/09/23/new-york-burger-week-pretzel-burger-beer-cheese"
    },
    {
      "id": 23359,
      "title": "Beef Burger Recipe (elvis Burger With Salad & Gherkin)",
      "imageType": "jpg",
      "sourceUrl": "http://www.jamieoliver.com/recipes/beef-recipes/elvis-burger-with-pickled-gherkin"
    },
    {
      "id": 149115,
      "title": "Surf N' Turf Burger (Grilled Burger with Lobster and Bacon)",
      "imageType": "jpg",
      "sourceUrl": "http://www.seriouseats.com/recipes/2013/06/lobster-bacon-burger-recipe.html"
    },
    {
      "id": 861442,
      "title": "Istanbul-Style Wet Burger (Islak Burger)",
      "imageType": "jpg",
      "sourceUrl": "http://www.epicurious.com/recipes/food/views/istanbul-style-wet-burger-islak-burger?mbid=nl_02272017_Daily_CTN_PM+(1)"
    },
    {
      "id": 600423,
      "title": "Rajma Burger (Red Kidney Beans Burger)",
      "imageType": "jpg",
      "sourceUrl": "http://www.spiceupthecurry.com/rajma-burger-red-kidney-beans-burger/"
    },
    {
      "id": 493634,
      "title": "Chicago Burger Week: The Chicago Deep Dish Pizza Burger",
      "imageType": "jpg",
      "sourceUrl": "http://www.foodrepublic.com/2013/09/30/chicago-burger-week-chicago-deep-dish-pizza-burger"
    },
    {
      "id": 487346,
      "title": "aloo tikki burger , north indian style aloo tikki burger",
      "imageType": "jpg",
      "sourceUrl": "http://www.vegrecipesofindia.com/aloo-tikki-burger/"
    },
    {
      "id": 607330,
      "title": "Aloo Tikki Burger | How to make aloo tikki burger at home",
      "imageType": "jpg",
      "sourceUrl": "http://www.spiceupthecurry.com/aloo-tikki-burger-recipe/"
    }
  ]
}

Quotas

Image Analysis by URL

Analyze a food image. The API tries to classify the image, guess the nutrition, and find a matching recipes. You can play around with that endpoint!

See here for a full list of supported categories.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
  "nutrition": {
    "recipesUsed": 25,
    "calories": {
      "value": 508,
      "unit": "calories",
      "confidenceRange95Percent": {
        "min": 428.97,
        "max": 571.98
      },
      "standardDeviation": 182.4
    },
    "fat": {
      "value": 21,
      "unit": "g",
      "confidenceRange95Percent": {
        "min": 21.29,
        "max": 32.95
      },
      "standardDeviation": 14.88
    },
    "protein": {
      "value": 29,
      "unit": "g",
      "confidenceRange95Percent": {
        "min": 22.58,
        "max": 33.7
      },
      "standardDeviation": 14.19
    },
    "carbs": {
      "value": 40,
      "unit": "g",
      "confidenceRange95Percent": {
        "min": 29.74,
        "max": 44.96
      },
      "standardDeviation": 19.42
    }
  },
  "category": {
    "name": "burger",
    "probability": 0.9998999999999999
  },
  "recipes": [
    {
      "id": 477749,
      "title": "Burger Club: Award-Winning Logan County Burger Patty Melt",
      "imageType": "jpg",
      "url": "http://www.barbarabakes.com/2010/05/burger-club-award-winning-logan-county/"
    },
    {
      "id": 493632,
      "title": "New York Burger Week: Pretzel Burger with Beer Cheese",
      "imageType": "jpg",
      "url": "http://www.foodrepublic.com/2013/09/23/new-york-burger-week-pretzel-burger-beer-cheese"
    },
    {
      "id": 23359,
      "title": "Beef Burger Recipe (elvis Burger With Salad & Gherkin)",
      "imageType": "jpg",
      "url": "http://www.jamieoliver.com/recipes/beef-recipes/elvis-burger-with-pickled-gherkin"
    },
    {
      "id": 149115,
      "title": "Surf N' Turf Burger (Grilled Burger with Lobster and Bacon)",
      "imageType": "jpg",
      "url": "http://www.seriouseats.com/recipes/2013/06/lobster-bacon-burger-recipe.html"
    },
    {
      "id": 861442,
      "title": "Istanbul-Style Wet Burger (Islak Burger)",
      "imageType": "jpg",
      "url": "http://www.epicurious.com/recipes/food/views/istanbul-style-wet-burger-islak-burger?mbid=nl_02272017_Daily_CTN_PM+(1)"
    },
    {
      "id": 600423,
      "title": "Rajma Burger (Red Kidney Beans Burger)",
      "imageType": "jpg",
      "url": "http://www.spiceupthecurry.com/rajma-burger-red-kidney-beans-burger/"
    },
    {
      "id": 493634,
      "title": "Chicago Burger Week: The Chicago Deep Dish Pizza Burger",
      "imageType": "jpg",
      "url": "http://www.foodrepublic.com/2013/09/30/chicago-burger-week-chicago-deep-dish-pizza-burger"
    },
    {
      "id": 487346,
      "title": "aloo tikki burger , north indian style aloo tikki burger",
      "imageType": "jpg",
      "url": "http://www.vegrecipesofindia.com/aloo-tikki-burger/"
    },
    {
      "id": 607330,
      "title": "Aloo Tikki Burger | How to make aloo tikki burger at home",
      "imageType": "jpg",
      "url": "http://www.spiceupthecurry.com/aloo-tikki-burger-recipe/"
    }
  ]
}

Quotas

Quick Answer

Answer a nutrition related natural language question.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "answer": "There are 16.74 mg of Vitamin C in 2 apples. This covers about 20% of your daily needs of Vitamin C.",
    "image": "https://img.spoonacular.com/ingredients_100x100/apple.jpg"
}

Quotas

Detect Food in Text

Take any text and find all mentions of food contained within it. This task is also called Named Entity Recognition (NER). In this case, the entities are foods. Either dishes, such as pizza or cheeseburger, or ingredients, such as cucumber or almonds.

Headers

Request Headers:

• Content-Type: application/x-www-form-urlencoded

Response Headers:

• Content-Type: application/json

Parameters

{
    "annotations": [
        {
            "annotation": "cheeseburger",
            "image": "https://spoonacular.com/menuItemImages/cheeseburger.jpg",
            "tag": "dish"
        },
        {
            "annotation": "mushrooms",
            "image": "https://img.spoonacular.com/ingredients_100x100/mushrooms.png",
            "tag": "ingredient"
        },
        {
            "annotation": "pepperoni",
            "image": "https://img.spoonacular.com/ingredients_100x100/pepperoni.png",
            "tag": "ingredient"
        },
        {
            "annotation": "tomatoes",
            "image": "https://img.spoonacular.com/ingredients_100x100/tomato.png",
            "tag": "ingredient"
        },
        {
            "annotation": "cheddar",
            "image": "https://img.spoonacular.com/ingredients_100x100/cheddar-cheese.png",
            "tag": "ingredient"
        },
        {
            "annotation": "tacos",
            "image": "https://spoonacular.com/menuItemImages/taco-isolated.jpg",
            "tag": "dish"
        },
        {
            "annotation": "pizza",
            "image": "https://spoonacular.com/menuItemImages/cheese-pizza.png",
            "tag": "dish"
        }
    ]
}

Interactive Demo

Change the text in the box and press "Detect". The detected dishes will be displayed in red and the detected ingredients in purple.

Quotas

Search Site Content

Search spoonacular's site content. You'll be able to find everything that you could also find using the search suggestions on spoonacular.com. This is a suggest API so you can send partial strings as queries.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "Articles": [
        {
            "dataPoints": [],
            "image": "https://spoonacular.com/application/frontend/images/academy/vietnamese-cuisine.jpg",
            "link": "https://spoonacular.com/academy/vietnamese",
            "name": "Traditional Vietnamese Recipes"
        },
        {
            "dataPoints": [],
            "image": "https://spoonacular.com/application/frontend/images/academy/thai-cuisine.jpg",
            "link": "https://spoonacular.com/academy/thai",
            "name": "Authentic Thai Recipes"
        },
        {
            "dataPoints": [],
            "image": "https://spoonacular.com/application/frontend/images/academy/korean-food.jpg",
            "link": "https://spoonacular.com/academy/korean",
            "name": "Typical Korean Recipes"
        }
    ],
    "Grocery Products": [
        {
            "dataPoints": [
                {
                    "key": "Calories",
                    "value": "30 Calories"
                },
                {
                    "key": "Protein",
                    "value": "2g Protein"
                },
                {
                    "key": "Fat",
                    "value": "0.0g Total Fat"
                },
                {
                    "key": "Carbs",
                    "value": "6g Carbs"
                }
            ],
            "image": "https://img.spoonacular.com/products/218909-312x231.jpg",
            "link": "https://spoonacular.com/products/vine-ripe-tomato-paste-218909",
            "name": "Vine-ripe Tomato Paste"
        },
        {
            "dataPoints": [
                {
                    "key": "Calories",
                    "value": "30 Calories"
                },
                {
                    "key": "Protein",
                    "value": "2g Protein"
                },
                {
                    "key": "Fat",
                    "value": "0.0g Total Fat"
                },
                {
                    "key": "Carbs",
                    "value": "6g Carbs"
                }
            ],
            "image": "https://img.spoonacular.com/products/178883-312x231.jpg",
            "link": "https://spoonacular.com/products/contadina-tomato-paste-178883",
            "name": "Contadina Tomato Paste"
        },
        {
            "dataPoints": [
                {
                    "key": "Calories",
                    "value": "30 Calories"
                },
                {
                    "key": "Protein",
                    "value": "2g Protein"
                },
                {
                    "key": "Fat",
                    "value": "0.0g Total Fat"
                },
                {
                    "key": "Carbs",
                    "value": "6g Carbs"
                }
            ],
            "image": "https://img.spoonacular.com/products/137031-312x231.jpg",
            "link": "https://spoonacular.com/products/cento-tomato-paste-137031",
            "name": "Cento Tomato Paste"
        }
    ],
    "Menu Items": [
        {
            "dataPoints": [
                {
                    "key": "Calories",
                    "value": "230 Calories"
                },
                {
                    "key": "Protein",
                    "value": "1g Protein"
                },
                {
                    "key": "Fat",
                    "value": "15g Total Fat"
                },
                {
                    "key": "Carbs",
                    "value": "23g Carbs"
                }
            ],
            "image": "https://spoonacular.com/menuItemImages/stir-fry.jpg",
            "link": "https://spoonacular.com/menu-items/thai-express-stir-fry-chilli-paste-401670",
            "name": "Thai Express Stir-Fry, Chilli Paste"
        }
    ],
    "Recipes": [
        {
            "dataPoints": [
                {
                    "key": "Cost",
                    "value": "$10.51 per serving"
                },
                {
                    "key": "Calories",
                    "value": "400 Calories"
                },
                {
                    "key": "Protein",
                    "value": "9g Protein"
                },
                {
                    "key": "Fat",
                    "value": "32g Total Fat"
                },
                {
                    "key": "Carbs",
                    "value": "26g Carbs"
                }
            ],
            "image": "https://img.spoonacular.com/recipes/224844-556x370.jpg",
            "link": "https://spoonacular.com/recipes/chermoula-paste-224844",
            "name": "Chermoula Paste"
        },
        {
            "dataPoints": [
                {
                    "key": "Cost",
                    "value": "$8.37 per serving"
                },
                {
                    "key": "Calories",
                    "value": "3560 Calories"
                },
                {
                    "key": "Protein",
                    "value": "119g Protein"
                },
                {
                    "key": "Fat",
                    "value": "319g Total Fat"
                },
                {
                    "key": "Carbs",
                    "value": "54g Carbs"
                }
            ],
            "image": "https://img.spoonacular.com/recipes/146847-556x370.jpg",
            "link": "https://spoonacular.com/recipes/lulu-paste-146847",
            "name": "Lulu Paste"
        },
        {
            "dataPoints": [
                {
                    "key": "Cost",
                    "value": "$6.68 per serving"
                },
                {
                    "key": "Calories",
                    "value": "990 Calories"
                },
                {
                    "key": "Protein",
                    "value": "53g Protein"
                },
                {
                    "key": "Fat",
                    "value": "86g Total Fat"
                },
                {
                    "key": "Carbs",
                    "value": "0.82g Carbs"
                }
            ],
            "image": "https://img.spoonacular.com/recipes/84670-556x370.jpg",
            "link": "https://spoonacular.com/recipes/steak-paste-84670",
            "name": "Steak Paste"
        }
    ]
}

Quotas

Search All Food

Search all food content with one call. That includes recipes, grocery products, menu items, simple foods (ingredients), and food videos.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
  "query": "apple",
  "totalResults": 5826,
  "limit": 2,
  "offset": 0,
  "searchResults": [
    {
      "name": "Recipes",
      "totalResults": 167,
      "results": [
        {
    	  "id": 632485,
          "name": "Apple Cake",
          "image": "https://img.spoonacular.com/recipes/632485-312x231.jpg",
          "link": "https://spoonacular.com/recipes/apple-cake-632485",
          "type": "HTML",
          "relevance": 10000,
          "content": "Apple Cake might be just the dessert you are searching for..."
        },
        {
    	  "id": 632522,
          "name": "Apple Crumble",
          "image": "https://img.spoonacular.com/recipes/632522-312x231.jpg",
          "link": "https://spoonacular.com/recipes/apple-crumble-632522",
          "type": "HTML",
          "relevance": 9999,
          "content": "Apple Crumble might be just the dessert you are searching for..."
        }
      ]
    },
    {
      "name": "Products",
      "totalResults": 3219,
      "results": [
        {
          "id": 428571,
          "name": "Pleasant Valley Apple Wine",
          "image": "https://img.spoonacular.com/products/469604-312x231.jpg",
          "link": "https://spoonacular.com/products/pleasant-valley-apple-wine-469604",
          "type": "HTML",
          "relevance": 10000
        },
        {
          "id": 428573,
          "name": "NV Georgetown Vineyards Apple Wine",
          "image": "https://img.spoonacular.com/products/428573-312x231.jpg",
          "link": "https://spoonacular.com/products/nv-georgetown-vineyards-apple-wine-428573",
          "type": "HTML",
          "relevance": 9999
        }
      ]
    },
    {
      "name": "Menu Items",
      "totalResults": 2410,
      "results": [
        {
    	  "id": 334550,
          "name": "Old Chicago Applewood Spiced BBQ Chicken Pizza, Chicago Thick, 12 Inch (Slice)",
          "image": null,
          "link": "https://spoonacular.com/menu-items/old-chicago-applewood-spiced-bbq-chicken-pizza-chicago-thick-12-inch--334550",
          "type": "HTML",
          "relevance": 10000
        },
        {
    	  "id": 422013,
          "name": "Huddle House Apple Cobbler a la mode",
          "image": null,
          "link": "https://spoonacular.com/menu-items/huddle-house-apple-cobbler-a-la-mode-422013",
          "type": "HTML",
          "relevance": 9999
        }
      ]
    },
    {
      "name": "Articles",
      "totalResults": 28,
      "results": [
        {
          "name": "Apples",
          "image": "https://img.spoonacular.com/ingredients_100x100/braeburn-apples.jpg",
          "link": "https://spoonacular.com/academy/apples",
          "type": "HTML",
          "relevance": 90.46
        },
        {
          "name": "Vinegar",
          "image": "https://img.spoonacular.com/ingredients_100x100/red-wine-vinegar.jpg",
          "link": "https://spoonacular.com/academy/vinegar",
          "type": "HTML",
          "relevance": 23.80
        }
      ]
    },
    {
      "name": "Videos",
      "totalResults": 2,
      "results": [
        {
    	  "id": "G0HENy59YkE",
          "name": "Pineapple Bundt Cake",
          "image": "https://i.ytimg.com/vi/G0HENy59YkE/hqdefault.jpg",
          "link": "https://www.youtube.com/watch?v=G0HENy59YkE",
          "type": "YOUTUBE_VIDEO",
          "relevance": 10000,
          "content": "FULL RECIPE HERE: https://tatyanaseverydayfood.com/recipe-items/pineapple-bundt-cake/..."
        },
        {
    	  "id": "xEENgO5Z5To",
          "name": "Pineapple Shrimp Tacos",
          "image": "https://i.ytimg.com/vi/xEENgO5Z5To/mqdefault.jpg",
          "link": null,
          "type": "YOUTUBE_VIDEO",
          "relevance": 9999,
          "content": "RECIPE: Below in description.\nThese Pineapple Shrimp Tacos cook in 5 minutes and assembly is a breeze..."
        }
      ]
    },
    {
      "name": "Simple Foods",
      "totalResults": 2,
      "results": [
        {
          "id": 78541,
          "name": "apple",
          "image": "apple.jpg",
          "type": "HTML",
          "relevance": 10000
        },
        {
    	  "id": 8782,
          "name": "applesauce",
          "image": "applesauce.png",
          "type": "HTML",
          "relevance": 9999
        }
      ]
    }
  ]
}

Quotas

Search Food Videos

Find recipe and other food related videos. This endpoint searches YouTube for relevant recipe or other food-related videos. Please be sure to read the YouTube Terms of Service before embedding videos into your site or app.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "videos": [
        {
            "title": "8 One-Pot Pastas",
            "length": 370,
            "rating": 0.985984219269103,
            "shortTitle": "8 One-Pot Pastas",
            "thumbnail": "https://i.ytimg.com/vi/YTZGPCCB2FU/mqdefault.jpg",
            "views": 550467,
            "youTubeId": "YTZGPCCB2FU"
        },
        {
            "title": "Macaroni salad - pasta salad recipes - healthy recipe channel - quick tasty recipe - cooking channel",
            "length": 333,
            "rating": 1.0,
            "shortTitle": "Macaroni salad",
            "thumbnail": "https://i.ytimg.com/vi/81bn4p8H3Kg/mqdefault.jpg",
            "views": 307,
            "youTubeId": "81bn4p8H3Kg"
        }
    ],
    "totalResults": 172
}

Quotas

Random Food Joke

Get a random joke that is related to food. Caution: this is an endpoint for adults!

Headers

Response Headers:

• Content-Type: application/json

{
    "text": "Any salad can be a Caesar salad if you stab it enough."
}

Quotas

Random Food Trivia

Returns random food trivia.

Headers

Response Headers:

• Content-Type: application/json

{
    "text": "The red food-coloring carmine used in Skittles and other candies is made from boiled cochineal bugs, a type of beetle."
}

Quotas

Get Ingredient Information

Use an ingredient id to get all available information about an ingredient, such as its image and supermarket aisle.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "id": 9266,
    "original": "pineapples",
    "originalName": "pineapples",
    "name": "pineapples",
    "amount": 1.0,
    "unit": "",
    "unitShort": "",
    "unitLong": "",
    "possibleUnits": [
        "piece",
        "slice",
        "fruit",
        "g",
        "oz",
        "cup",
        "serving"
    ],
    "estimatedCost": {
        "value": 299.0,
        "unit": "US Cents"
    },
    "consistency": "solid",
    "shoppingListUnits": [
        "pieces"
    ],
    "aisle": "Produce",
    "image": "pineapple.jpg",
    "meta": [],
    "nutrition": {
        "nutrients": [
            {
                "name": "Calories",
                "amount": 452.5,
                "unit": "cal",
                "percentOfDailyNeeds": 22.63
            },
            {
                "name": "Fat",
                "amount": 1.09,
                "unit": "g",
                "percentOfDailyNeeds": 1.67
            },
            {
                "name": "Saturated Fat",
                "amount": 0.08,
                "unit": "g",
                "percentOfDailyNeeds": 0.51
            },
            {
                "name": "Carbohydrates",
                "amount": 118.74,
                "unit": "g",
                "percentOfDailyNeeds": 39.58
            },
            {
                "name": "Net Carbohydrates",
                "amount": 106.07,
                "unit": "g",
                "percentOfDailyNeeds": 38.57
            },
            {
                "name": "Sugar",
                "amount": 89.14,
                "unit": "g",
                "percentOfDailyNeeds": 99.05
            },
            {
                "name": "Cholesterol",
                "amount": 0.0,
                "unit": "mg",
                "percentOfDailyNeeds": 0.0
            },
            {
                "name": "Sodium",
                "amount": 9.05,
                "unit": "mg",
                "percentOfDailyNeeds": 0.39
            },
            {
                "name": "Protein",
                "amount": 4.89,
                "unit": "g",
                "percentOfDailyNeeds": 9.77
            },
            {
                "name": "Vitamin C",
                "amount": 432.59,
                "unit": "mg",
                "percentOfDailyNeeds": 524.35
            },
            {
                "name": "Manganese",
                "amount": 8.39,
                "unit": "mg",
                "percentOfDailyNeeds": 419.47
            },
            {
                "name": "Fiber",
                "amount": 12.67,
                "unit": "g",
                "percentOfDailyNeeds": 50.68
            },
            {
                "name": "Vitamin B6",
                "amount": 1.01,
                "unit": "mg",
                "percentOfDailyNeeds": 50.68
            },
            {
                "name": "Copper",
                "amount": 1.0,
                "unit": "mg",
                "percentOfDailyNeeds": 49.78
            },
            {
                "name": "Vitamin B1",
                "amount": 0.72,
                "unit": "mg",
                "percentOfDailyNeeds": 47.66
            },
            {
                "name": "Folate",
                "amount": 162.9,
                "unit": "µg",
                "percentOfDailyNeeds": 40.73
            },
            {
                "name": "Potassium",
                "amount": 986.45,
                "unit": "mg",
                "percentOfDailyNeeds": 28.18
            },
            {
                "name": "Magnesium",
                "amount": 108.6,
                "unit": "mg",
                "percentOfDailyNeeds": 27.15
            },
            {
                "name": "Vitamin B3",
                "amount": 4.53,
                "unit": "mg",
                "percentOfDailyNeeds": 22.63
            },
            {
                "name": "Vitamin B5",
                "amount": 1.93,
                "unit": "mg",
                "percentOfDailyNeeds": 19.28
            },
            {
                "name": "Vitamin B2",
                "amount": 0.29,
                "unit": "mg",
                "percentOfDailyNeeds": 17.04
            },
            {
                "name": "Iron",
                "amount": 2.62,
                "unit": "mg",
                "percentOfDailyNeeds": 14.58
            },
            {
                "name": "Calcium",
                "amount": 117.65,
                "unit": "mg",
                "percentOfDailyNeeds": 11.77
            },
            {
                "name": "Vitamin A",
                "amount": 524.9,
                "unit": "IU",
                "percentOfDailyNeeds": 10.5
            },
            {
                "name": "Zinc",
                "amount": 1.09,
                "unit": "mg",
                "percentOfDailyNeeds": 7.24
            },
            {
                "name": "Phosphorus",
                "amount": 72.4,
                "unit": "mg",
                "percentOfDailyNeeds": 7.24
            },
            {
                "name": "Vitamin K",
                "amount": 6.34,
                "unit": "µg",
                "percentOfDailyNeeds": 6.03
            },
            {
                "name": "Selenium",
                "amount": 0.91,
                "unit": "µg",
                "percentOfDailyNeeds": 1.29
            },
            {
                "name": "Vitamin E",
                "amount": 0.18,
                "unit": "mg",
                "percentOfDailyNeeds": 1.21
            }
        ],
        "properties": [
            {
                "name": "Glycemic Index",
                "amount": 58.67,
                "unit": ""
            },
            {
                "name": "Glycemic Load",
                "amount": 62.23,
                "unit": ""
            }
        ],
        "flavonoids": [
            {
                "name": "Cyanidin",
                "amount": 0.0,
                "unit": "mg"
            }
        ],
        "caloricBreakdown": {
            "percentProtein": 3.88,
            "percentFat": 1.94,
            "percentCarbs": 94.18
        },
        "weightPerServing": {
            "amount": 905,
            "unit": "g"
        }
    },
    "categoryPath": [
        "tropical fruit",
        "fruit"
    ]
}

Quotas

Talk to Chatbot

This endpoint can be used to have a conversation about food with the spoonacular chatbot. Use the "Conversation Suggests" endpoint to show your user what he or she can say.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "answerText": "Baby, if you were a fruit you'd be a fineapple.",
    "media": []
}

Learn more

See how you can write your own chatbot or test spoonacular's food chatbot.

Quotas

Conversation Suggests

This endpoint returns suggestions for things the user can say or ask the chatbot.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "suggests": {
        "_": [
            {
                "name": "Tell me something funny"
            },
            {
                "name": "Tell me a food fact"
            },
            {
                "name": "Tell me a joke"
            },
            {
                "name": "Tell me food trivia"
            },
            {
                "name": "Tell me a fact about food"
            }
        ]
    },
    "words": []
}

Quotas

Nutrition

Food objects (whole foods, recipes, grocery products, menu items) have nutrition. Endpoints that expose nutritional information group nutrition into three categories: Nutrients (Macro and Micro), Food Properties, and Flavonoids.

Nutrients - Macro and Micro Nutrients

• Calories (in kcal)
• Fat (in g)
• Trans Fat (in g)
• Saturated Fat (in g)
• Mono Unsaturated Fat (in g)
• Poly Unsaturated Fat (in g)
• Protein (in g)
• Cholesterol (in mg)
• Carbohydrates (in g)
• Net Carbohydrates (in g)
• Alcohol (in g)
• Fiber (in g)
• Sugar (in g)
• Sodium (in mg)
• Caffein (in mg)
• Manganese (in mg)
• Potassium (in mg)
• Magnesium (in mg)
• Calcium (in mg)
• Copper (in mg)
• Zinc (in mg)
• Phosphorus (in mg)
• Fluoride (in mg)
• Choline (in mg)
• Iron (in mg)
• Vitamin A (in IU)
• Vitamin B1 (in mg)
• Vitamin B2 (in mg)
• Vitamin B3 (in mg)
• Vitamin B5 (in mg)
• Vitamin B6 (in mg)
• Vitamin B12 (in µg)
• Vitamin C (in mg)
• Vitamin D (in µg)
• Vitamin E (in mg)
• Vitamin K (in µg)
• Folate (in µg)
• Folic Acid (in µg)
• Iodine (in µg)
• Selenium (in µg)

Food Properties

• Glycemic Index
• Glycemic Load

Flavonoids

Flavonoids are food compounds called phytonutrients, which are found in many plants (fruit and vegetables) that have multiple health benefits.

• Cyanidin (in mg)
• Petunidin (in mg)
• Delphinidin (in mg)
• Malvidin (in mg)
• Pelargonidin (in mg)
• Peonidin (in mg)
• Catechin (in mg)
• Epigallocatechin (in mg)
• Epicatechin (in mg)
• Epicatechin 3-gallate (in mg)
• Epigallocatechin 3-gallate (in mg)
• Theaflavin (in mg)
• Theaflavin-3,3'-digallate (in mg)
• Theaflavin-3'-gallate (in mg)
• Theaflavin-3-gallate (in mg)
• Thearubigins (in mg)
• Eriodictyol (in mg)
• Hesperetin (in mg)
• Naringenin (in mg)
• Apigenin (in mg)
• Luteolin (in mg)
• Isorhamnetin (in mg)
• Kaempferol (in mg)
• Myricetin (in mg)
• Quercetin (in mg)
• Gallocatechin (in mg)

List of Ingredients

If you need ingredient names in your application, you can download a list of the 1,000 most frequently used ingredients including their id so you can call the API for more information. You are allowed to cache this list on your end but it is advised to update it every once in a while due to possible ingredient id changes.

List of Pantry Items

If you need ingredient names in your application, you can download a list of the 1,000 most frequently used ingredients including their id so you can call the API for more information. You are allowed to cache this list on your end but it is advised to update it every once in a while due to possible ingredient id changes.

• Water (id: 14412)
• Ice (id: 10014412)
• Flour (id: 20081)
• Sugar (id: 19335)
• Cane Sugar (id: 10719335)
• Olive Oil (id: 4053)
• Cooking Fat (id: 1004513)
• Cooking Oil (id: 4582)
• Vegetable Oil (id: 4513)
• Black Pepper (id: 1002030)
• Sea Salt (id: 1012047)
• Salt (id: 2047)

List of Supermarket Aisles

• Baking
• Health Foods
• Spices and Seasonings
• Pasta and Rice
• Bakery/Bread
• Refrigerated
• Canned and Jarred
• Frozen
• Nut butters, Jams, and Honey
• Oil, Vinegar, Salad Dressing
• Condiments
• Savory Snacks
• Milk, Eggs, Other Dairy
• Ethnic Foods
• Tea and Coffee
• Meat
• Gourmet
• Sweet Snacks
• Gluten Free
• Alcoholic Beverages
• Cereal
• Nuts
• Beverages
• Produce
• Not in Grocery Store/Homemade
• Seafood
• Cheese
• Dried Fruits
• Online
• Grilling Supplies
• Bread

Search Restaurants

Search through thousands of restaurants (in North America) by location, cuisine, budget, and more.

Headers

Response Headers:

• Content-Type: application/json

Parameters

{
    "restaurants": [
        {
            "_id": "a8b49c84-a92d-4f06-802e-467af49feaf0",
            "name": "South Beach Cafe",
            "phone_number": 14159741115,
            "address": {
                "street_addr": "800 The Embarcadero",
                "city": "San Francisco",
                "state": "CA",
                "zipcode": "94107",
                "country": "US",
                "lat": 37.78129959,
                "lon": -122.38869477,
                "street_addr_2": "",
                "latitude": 37.78129959,
                "longitude": -122.38869477
            },
            "type": "restaurant",
            "description": "Italian, Pizza",
            "local_hours": {
                "operational": {
                    "Monday": "07:00AM - 09:00PM",
                    "Tuesday": "07:00AM - 09:00PM",
                    "Wednesday": "07:00AM - 09:00PM",
                    "Thursday": "07:00AM - 09:00PM",
                    "Friday": "07:00AM - 09:00PM",
                    "Saturday": "08:00AM - 09:00PM",
                    "Sunday": "08:00AM - 09:00PM"
                },
                "delivery": {
                    "Monday": "07:00AM - 09:00PM",
                    "Tuesday": "07:00AM - 09:00PM",
                    "Wednesday": "07:00AM - 09:00PM",
                    "Thursday": "07:00AM - 09:00PM",
                    "Friday": "07:00AM - 09:00PM",
                    "Saturday": "08:00AM - 09:00PM",
                    "Sunday": "08:00AM - 09:00PM"
                },
                "pickup": {
                    "Monday": "07:00AM - 09:00PM",
                    "Tuesday": "07:00AM - 09:00PM",
                    "Wednesday": "07:00AM - 09:00PM",
                    "Thursday": "07:00AM - 09:00PM",
                    "Friday": "07:00AM - 09:00PM",
                    "Saturday": "08:00AM - 09:00PM",
                    "Sunday": "08:00AM - 09:00PM"
                },
                "dine_in": {
                    "Monday": "07:00AM - 09:00PM",
                    "Tuesday": "07:00AM - 09:00PM",
                    "Wednesday": "07:00AM - 09:00PM",
                    "Thursday": "07:00AM - 09:00PM",
                    "Friday": "07:00AM - 09:00PM",
                    "Saturday": "08:00AM - 09:00PM",
                    "Sunday": "08:00AM - 09:00PM"
                }
            },
            "cuisines": [
                "Breakfast",
                "Dinner",
                "Italian",
                "Lunch",
                "Pickup",
                "Pizza",
                "Salads",
                "Sandwich",
                "Sandwiches",
                "Takeout"
            ],
            "food_photos": [
                "https://cdn-img.mealme.ai/f3d0e396f1b552927092bafa65ef2cc4e8b57c22/68747470733a2f2f6d656469612d63646e2e677275626875622e636f6d2f696d6167652f75706c6f61642f62657462706b3570747a37756a306279616b6a672e6a7067"
            ],
            "logo_photos": [
                "https://cdn-img.mealme.ai/25b450d4e72eea47dccd744c326e49e23343bd0d/68747470733a2f2f7265732e636c6f7564696e6172792e636f6d2f677275626875622f696d6167652f75706c6f61642f76313531383830323236382f63686a6a356173716f6766696e726f7671376f732e706e67"
            ],
            "store_photos": [],
            "dollar_signs": 2,
            "pickup_enabled": true,
            "delivery_enabled": true,
            "is_open": false,
            "offers_first_party_delivery": false,
            "offers_third_party_delivery": true,
            "miles": 0.2508434381960197,
            "weighted_rating_value": 4.725654450261779,
            "aggregated_rating_count": 191
        },
        ...
    ]
}

Quotas

Wine Guide

Here you can see the classification spoonacular uses for wines. If you are missing a wine please let us know!

Classification of Wines

wine
 - white_wine
   - dry_white_wine
     - assyrtiko
     - pinot_blanc
     - cortese
     - roussanne
     - moschofilero
     - muscadet
     - viognier
     - verdicchio
     - greco
     - marsanne
     - white_burgundy
     - chardonnay
     - gruener_veltliner
     - white_rioja
     - frascati
     - gavi
     - l_acadie_blanc
     - trebbiano
     - sauvignon_blanc
     - catarratto
     - albarino
     - arneis
     - verdejo
     - vermentino
     - soave
     - pinot_grigio
     - dry_riesling
     - torrontes
   - mueller_thurgau
   - grechetto
   - gewurztraminer
   - chenin_blanc
   - white_bordeaux
   - semillon
   - riesling
   - sauternes
   - sylvaner
   - lillet_blanc
 - red_wine
   - dry_red_wine
     - petite_sirah
     - zweigelt
     - baco_noir
     - bonarda
     - cabernet_franc
     - bairrada
     - barbera_wine
     - primitivo
     - pinot_noir
     - nebbiolo
     - dolcetto
     - tannat
     - negroamaro
     - red_burgundy
     - corvina
     - rioja
     - cotes_du_rhone
     - grenache
     - malbec
     - zinfandel
     - sangiovese
     - carignan
     - carmenere
     - cesanese
     - cabernet_sauvignon
     - aglianico
     - tempranillo
     - shiraz
     - mourvedre
     - merlot
     - nero_d_avola
   - bordeaux
   - marsala
   - port
   - gamay
   - dornfelder
   - concord_wine
   - sparkling_red_wine
   - pinotage
   - agiorgitiko
 - dessert_wine
   - pedro_ximenez
   - moscato
   - late_harvest
   - ice_wine
   - white_port
   - lambrusco_dolce
   - madeira
   - banyuls
   - vin_santo
   - port
 - rose_wine
   - sparkling_rose
 - sparkling_wine
   - cava
   - cremant
   - champagne
   - prosecco
   - spumante
   - sparkling_rose
 - sherry
   - cream_sherry
   - dry_sherry
 - vermouth
   - dry_vermouth
 - fruit_wine
 - mead

Working with the Meal Planner

The spoonacular API allows you to interact with the spoonacular meal planner. Check out the endpoints under "Meal Planning" on the left to see what you can do.

Since meal plans and shopping lists are user-specific, you need to also pass a username and the user's hash besides your apiKey. This guarantees that you have the user's rights to manipulate her meal plan and/or shopping list.

If you want to create a meal planner like spoonacular's you can use these endpoints to realize it.

Here's an example workflow:

1. Connect your app's user with spoonacular by calling Connect User.
2. During step one you will get the user's username and hash from spoonacular. Save this on your side and connect it to your user. This allows you to make requests on the user's behalf.
3. Now you can use the meal planning endpoints. For example, your app could do the following:
   1. Offer the user existing meal plans (e.g. vegetarian or keto meal plans) by calling Get Meal Plan Templates.
   2. Let the user add recipes, products, or simple foods to her meal plan via the Add to Meal Plan endpoint.
   3. Now that the user has food on the meal plan, you can let her generate a shopping list by calling the Generate Shopping List endpoint.
   4. If the user then is in the store you can show her the current shopping list via the Get Shopping List endpoint and let her remove items as she buys them using the Delete from Shopping List endpoint.

Feel free to reach out to us if you'd like to see specific functionality that we currently do not list here.

Show Images

Ingredients

Endpoints like the ingredient autosuggestion will only give you an image name. You have to build the full URL by adding the base path to the beginning. The base path for ingredient images is https://img.spoonacular.com/ingredients_{SIZE}/, where {SIZE} is one of the following:

• 100x100
• 250x250
• 500x500

So for "apple.jpg" the full path for 100x100 is https://img.spoonacular.com/ingredients_100x100/apple.jpg

Cooking Equipment

The recipe instruction endpoint will give you information about the equipment used for cooking the dish. You will again only receive the image name for the equipment. You have to build the full URL by adding the base path to the beginning. The base path for equipment images is https://img.spoonacular.com/equipment_{SIZE}/, where {SIZE} is one of the following:

• 100x100
• 250x250
• 500x500

So for "slow-cooker.jpg" the full path for 100x100 is https://img.spoonacular.com/equipment_100x100/slow-cooker.jpg

Recipes

Recipe endpoints will almost always give you a recipe id {ID}. With that and the imageType {TYPE} you can build the complete image paths depending on your needs.

The base path for image URLs is https://img.spoonacular.com/recipes/. Once you know the recipe id {ID} and image type {TYPE}, you can complete that path to show an image. The complete path follows this pattern https://img.spoonacular.com/recipes/{ID}-{SIZE}.{TYPE}, where {SIZE} is one of the following:

• 90x90
• 240x150
• 312x150
• 312x231
• 480x360
• 556x370
• 636x393

A complete image path might look like this: https://img.spoonacular.com/recipes/579247-556x370.jpg

Or this: https://img.spoonacular.com/recipes/579247-90x90.jpg

Grocery Products

Grocery product endpoints will almost always give you a product id {ID}. With that and the imageType {TYPE} you can build the complete image paths depending on your needs.

The base path for image URLs is https://img.spoonacular.com/products/. Once you know the product id {ID} and image type {TYPE}, you can complete that path to show an image. The complete path follows this pattern https://img.spoonacular.com/products/{ID}-{SIZE}.{TYPE}, where {SIZE} is one of the following:

• 90x90
• 312x231
• 636x393

A complete image path might look like this: https://img.spoonacular.com/products/35507-636x393.jpeg

Or this: https://img.spoonacular.com/products/35507-90x90.jpeg

Menu Items

Menu item will almost always give you a menu item id {ID}. With that and the imageType {TYPE} you can build the complete image paths depending on your needs.

The base path for image URLs is https://img.spoonacular.com/menu-items/. Once you know the menu item id {ID} and image type {TYPE}, you can complete that path to show an image. The complete path follows this pattern https://img.spoonacular.com/menu-items/{ID}-{SIZE}.{TYPE}, where {SIZE} is one of the following:

• 90x90
• 312x231
• 636x393

A complete image path might look like this: https://img.spoonacular.com/menu-items/423186-636x393.png

Or this: https://img.spoonacular.com/menu-items/423186-90x90.png

Intolerances

Every API endpoint asking for a intolerances parameter can be fed with any of these intolerances.

• Dairy
• Egg
• Gluten
• Grain
• Peanut
• Seafood
• Sesame
• Shellfish
• Soy
• Sulfite
• Tree Nut
• Wheat

Meal Types

Every API endpoint asking for a type parameter can be fed with any of these meal types.

• main course
• side dish
• dessert
• appetizer
• salad
• bread
• breakfast
• soup
• beverage
• sauce
• marinade
• fingerfood
• snack
• drink

Recipe Sorting Options

This is a list of possible values for the sort parameter of the complex recipe search endpoint.

• (empty)
• meta-score
• popularity
• healthiness
• price
• time
• random
• max-used-ingredients
• min-missing-ingredients
• alcohol
• caffeine
• copper
• energy
• calories
• calcium
• carbohydrates
• carbs
• choline
• cholesterol
• total-fat
• fluoride
• trans-fat
• saturated-fat
• mono-unsaturated-fat
• poly-unsaturated-fat
• fiber
• folate
• folic-acid
• iodine
• iron
• magnesium
• manganese
• vitamin-b3
• niacin
• vitamin-b5
• pantothenic-acid
• phosphorus
• potassium
• protein
• vitamin-b2
• riboflavin
• selenium
• sodium
• vitamin-b1
• thiamin
• vitamin-a
• vitamin-b6
• vitamin-b12
• vitamin-c
• vitamin-d
• vitamin-e
• vitamin-k
• sugar
• zinc

Health Score ('healthiness')

Score % (between 0 and 100) = Average coverage of "good" nutrients - Average coverage of "bad" nutrients.

That is, the more of your daily requirements of vitamins and minerals are covered and lower amounts of things you should limit (sugar, salt etc.) the higher the score.

Cuisines

Every API endpoint asking for a cuisine parameter can be fed with any of these cuisines.

• African
• Asian
• American
• British
• Cajun
• Caribbean
• Chinese
• Eastern European
• European
• French
• German
• Greek
• Indian
• Irish
• Italian
• Japanese
• Jewish
• Korean
• Latin American
• Mediterranean
• Mexican
• Middle Eastern
• Nordic
• Southern
• Spanish
• Thai
• Vietnamese

Image Classification Categories

The image classification and image analysis API endpoints can detect the following classes.

• agnolotti
• ahi_tuna
• antipasto_salad
• apple_cake
• babka
• baked_apple
• baked_beans
• baked_potato
• baked_salmon
• baklava
• beef_ribs
• beef_stew
• beef_stroganoff
• beer
• bibimbap
• biscotti
• brisket
• brownies
• burger
• burrito
• calzone
• caprese_salad
• cheesecake
• chicken_nuggets
• chicken_wings
• chili
• chow_mein
• chowder
• churros
• coffee
• coleslaw
• cookies
• creme_brulee
• crepes
• cupcakes
• donut
• falafel
• fish_and_chips
• french_toast
• fruit_salad
• gyros
• ice_cream
• lasagne
• lobster_roll
• macarons
• nachos
• omelet
• paella
• pancakes
• sushi

Interested in learning more? Read the entire article.

Image Classification

This article compares 7 online image recognition services in the context of food recognition. In particular, my goal was to find out which service is best suited to recognize and classify the dish you ordered in a restaurant based on a picture you took.

There are plenty of services out there, but I decided to compare the following as they are leaders in the field and have stable APIs:

Image analysis by Amazon. They do not seem to have a pre-trained food model, so I used their generic tagger. Each classified image comes back with a number of tags and confidences.

An image analysis service that also features a special food model, which I used for testing.

An image analysis service by Google that also does not come with a pre-trained food model.

Another image analysis service without a pre-trained food model. I used their generic tagger.

An image analysis service or (as they call it) "cognitive service" by Microsoft. No food model available.

IBM Watson for image analysis by IBM. IBM also created a pre-trained food-specific model that I was able to use in their API.

The spoonacular food API offers a food-specific model specifically trained on our test dataset.

Okay, now that we know our contenders, let's take a look at what dataset we're working with.

The 50-Class Food Dataset

Our goal is to build/test a food dish recognizer. That is, we don't want to recognize single ingredients, such as an apple, milk, or a cup of mushrooms, but rather complex dishes that you would order in a restaurant.

To achieve this, we used the spoonacular food ontology to create a set of 518 dishes and gathered 2,781,306 images in total (over 417 GB in file size). The spoonacular food ontology is rather fine-grained, so many of the dish categories were a bit too specific (e.g. "lemon cookies"), so I reduced it down to 50 common classes with about 300 manually checked images per class.

The final dataset is 50 classes with a total of 15,742 images (4.4 GB in size).

The images are a mixture of high quality, professional photographs (showing the perfect execution of the dish, usually NOT taken in a real restaurant setting) and "real world" images taken by people that actually ordered and received that dish (like pictures taken from the spoonacular food journal). The differences between the two types are often extreme, so I found it to be valuable to have both types in the dataset.

Have a look at the following example classes, "cookies", "burger", and "pancakes":

Now, here is the full list of the 50 food categories with images (here in plain text):

Comparison of Image Classification Services

Now that we know the dataset we're working with we can test the services with pictures from the dataset. These tests can only give us a rough idea of how well the service works because, as stated earlier, not all of them have a food-specific model. More importantly, they are trained on a completely different taxonomy, which means they might not even know what "bibimbap" is or what "churros" look like.

The goal of this article, however, is to find out which services are well suited for real-world dish recognition without training your own models (as dataset preparation is the really hard part). In this context, it is fair to compare them against an unknown set of images and see what they think the images are.

I classified the same 50 images per class using each service for 2,500 classifications in total. The super long image below shows the top 5 tags/categories that each service assigned the images for each class. The percentage after the classified category is the percentage of images that received that particular tag. For example, Amazon Rekognition classified 98% of the "agnolotti" images as "Food". Good start.

Additionally, I bolded the category names which we should consider correct for the given images. Since the other taxonomies are not exactly the same as spoonacular's, we should still count "doughnut" as correct even if the spoonacular class is "donut".

The spoonacular column is just there for reference—since spoonacular's classifier was trained using the dataset, the category names always match and the percentage of matches is of course often higher.

The last row in the table shows how many classes in the top 5 can be considered correct. Aside from the expected 50/50 for spoonacular, we can see that the two services with special food-related classifiers, Clarifai and Watson, outperformed the other services dramatically.

In particular, the Watson food classifier seems to have been trained on a more fine-grained taxonomy. This is not surprising, since they say they have 2,000 tags, ranging from specific dishes to broader categories like "sweet" and "delicacy" as well. They even differentiate between "barbecued wing" and "buffalo wing"!

To give you an idea which tags/categories each service assigned to the provided images, here are the top 50 tags for each service (for all 2,500 classified images). You can also download the raw data if you're interested in seeing it all.

Top 50 Classes for Amazon Rekognition

Amazon answered with 1,029 different tags, which is to be expected for a general classifier. The funniest tags were "T-Rex", "dynamite", and "toilet" :)

Top 50 Classes for Clarifai

Clarifai answered with a total of 740 different food-specific tags (remember, they have a food-specific model). Looking at the tags with a low frequency we can see that they don't only use dishes in their model, but also have plain ingredients such as "starfruit", "watercress", and even spices like "cumin" in their model.

Top 50 Classes for Google Cloud Vision

Google only had a generic model, which shows in the poor results. They answered with a total of 1,831 distinct tags, most of them food-related and some controversial ones like "shark fin soup" and "foie gras" as well.

Top 50 Classes for Imagga

Imagga answered with a total of 832 distinct tags from their generic model. While most of them were food related, I also got back "concrete", "snake", and "winter" at times.

Top 50 Classes for Microsoft Cloud Vision

Microsoft Cognitive Services' generic model came back with at total of 1,070 distinct tags - most of them food related.

Top 50 Classes for IBM Watson

Watson returned 873 distinct food-related tags from the food model.

spoonacular Confusion Matrix

For spoonacular, we were able to create an actual confusion matrix. The y-axis shows the tested classes and the x-axis the model's prediction. The diagonal (top left to bottom right) shows correct classifications.

The total accuracy of spoonacular's model is 90%. Most problematic seems to be "baked apple" with only 71% accuracy, while "beer" and "burger" are recognized with 100% accuracy - cheers to that!

Resources and Tools Used

To run all the tests I used the Palladian Java Toolkit. Its wrappers for the cloud services Clarifai, Imagga, Amazon Rekognition, IBM Watson, Google Cloud Vision, and Microsoft Cloud Vision made evaluation much easiser.

Thanks to Björn Hempel for writing his bachelor thesis on this topic, which you can read here.

If you're interested in more detailed information you can download the raw data (Excel).

Summary

If you want to reliably tag food-related images, you may want to use a service that comes with a pre-trained food model such as Clarifai, Watson, or spoonacular. If you have the time, knowledge, and resources, you can of course create your own dataset and create a custom model. Most online services allow for custom training models, but dataset creation is definitely not to be underestimated.

Also, if you want to play around with the spoonacular dish classifier, I built this demo.

Diet Definitions

Every API endpoint asking for an diet parameter can be fed with any of these diets.

Gluten Free

Eliminating gluten means avoiding wheat, barley, rye, and other gluten-containing grains and foods made from them (or that may have been cross contaminated).

Ketogenic

The keto diet is based more on the ratio of fat, protein, and carbs in the diet rather than specific ingredients. Generally speaking, high fat, protein-rich foods are acceptable and high carbohydrate foods are not. The formula we use is 55-80% fat content, 15-35% protein content, and under 10% of carbohydrates.

Vegetarian

No ingredients may contain meat or meat by-products, such as bones or gelatin.

Lacto-Vegetarian

All ingredients must be vegetarian and none of the ingredients can be or contain egg.

Ovo-Vegetarian

All ingredients must be vegetarian and none of the ingredients can be or contain dairy.

Vegan

No ingredients may contain meat or meat by-products, such as bones or gelatin, nor may they contain eggs, dairy, or honey.

Pescetarian

Everything is allowed except meat and meat by-products - some pescetarians eat eggs and dairy, some do not.

Paleo

Allowed ingredients include meat (especially grass fed), fish, eggs, vegetables, some oils (e.g. coconut and olive oil), and in smaller quantities, fruit, nuts, and sweet potatoes. We also allow honey and maple syrup (popular in Paleo desserts, but strict Paleo followers may disagree). Ingredients not allowed include legumes (e.g. beans and lentils), grains, dairy, refined sugar, and processed foods.

Primal

Very similar to Paleo, except dairy is allowed - think raw and full fat milk, butter, ghee, etc.

Low FODMAP

FODMAP stands for "fermentable oligo-, di-, mono-saccharides and polyols". Our ontology knows which foods are considered high in these types of carbohydrates (e.g. legumes, wheat, and dairy products)

Whole30

Allowed ingredients include meat, fish/seafood, eggs, vegetables, fresh fruit, coconut oil, olive oil, small amounts of dried fruit and nuts/seeds. Ingredients not allowed include added sweeteners (natural and artificial, except small amounts of fruit juice), dairy (except clarified butter or ghee), alcohol, grains, legumes (except green beans, sugar snap peas, and snow peas), and food additives, such as carrageenan, MSG, and sulfites.

See also the comparison of popular diets

How to Write a Chatbot

Here is an easy way how to make a chatbot like the spoonacular chatbot with JavaScript in 10 minutes.

• Check out this JavaScript chatbot repository on GitHub.
• Follow the instructions in the readme file.
• Optionally, if you want spoonacular support in your bot: Sign up for a RapidAPI key.

Rate Limiting & Quotas

When you are on the free plan and your daily quota is used up, the API will respond with the error code 402 and no more calls can be made until your quota resets.

You have complete control over your quota by looking at your console dashboard and checking the API response headers that appear with every answer from the API. These response headers are:

• X-API-Quota-Request: The number of points used by the request.
• X-API-Quota-Used: The number of points used in total today. This number resets to zero at midnight UTC (click here to compare to your local time zone).
• X-API-Quota-Left: The number of points left today (depends on your plan).

Rate Limiting

There is a limit of how many requests you can make per second. The limits depend on the plan you are on. If you try making more requests you will receive a 429 error.

• Free: 60 requests in 1 minute
• Starter: 120 requests in 1 minute
• Cook: 5 requests per second
• Culinarian: 10 requests per second
• Chef: 20 requests per second

Authentication

To use the API you need an API key. You can get a free one by simply signing up here.

Once you have your API key, you have to put it in the request URL for every request you make like so ?apiKey=YOUR-API-KEY.

Attention: Only the first query parameter is prefixed with a ? (question mark), all subsequent ones will be prefixed with a & (ampersand). That is how URLs work and nothing related to our API. Here's a full example with two parameters apiKey and includeNutrition: https://api.spoonacular.com/recipes/716429/information?apiKey=YOUR-API-KEY&includeNutrition=true.

Please further note that parameters are case sensitive, it is apiKey not apikey.

Alternatively, you can put the API key in the request header as x-api-key.