Searching Recipes

Learn about the different ways you can search for recipes using the Spoonacular API.

We'll cover the following

We can use the Spoonacular API to add a powerful recipe search engine to our projects. To do so, we can use the following endpoints based on our use case:

  • search recipes
  • search recipes nutrients
  • search recipes ingredients

The search recipes endpoint

The search recipes endpoint performs a complex search and fetches recipes for a given query. However, we can easily use most query parameters of other recipe search endpoints for advanced filtering. The search recipes endpoint has a cost of 11quota point while each recipe returned has a cost of 0.010.01quota points. There will be an additional cost of 11quota point if any nutrient filter parameter is used. The endpoint method and the URL are as follows:

GET https://api.spoonacular.com/recipes/complexSearch

Here are some of the request parameters we can use with the search recipes endpoint when performing a recipe search:

Request Parameters

Parameter

Type

Category

Description

query

String

Optional

The search query to look up the recipe.

cuisine

String

Optional

Accepts a single cuisine or a comma-separated list of cuisines. The API will interpret the comma as an OR connection.

excludeCuisine

String

Optional

Excludes any associated recipes from the search results and accepts a single cuisine or a comma-separated list of cuisines. The API will interpret the comma as an AND connection.

diet

String

Optional

Accepts a single diet or a list of diets. We can separate list elements by , or |. The API will interpret , as an AND connection and | as an OR connection.

intolerances

String

Optional

Accepts a single intolerance or a comma-separated list of intolerances.

equipment

String

Optional

Accepts a comma-separated list of equipment.

includeIngredients

String

Optional

Accepts a comma-separated list of ingredients.

excludeIngredients

String

Optional

The ingredient(s) that the queried recipes should not use. This parameter accepts a comma-separated list of ingredients.

type

String

Optional

The meal type of the queried recipes.

limitLicense

Boolean

Optional

The option, if set to true, ensures the API will only fetch recipes with an open license, allowing for proper attribution

Note: For additional request parameters, refer to the "Additional Request Parameters" lesson. A complete list of all supported cuisine values can be found in the "Supported Parameter Values" lesson.

Let’s see how to call the API endpoint to query recipes. Click the “Run” button to execute the code.

Press + to interact
// Importing libraries here
import fetch from 'node-fetch';
// Define endpoint URL here
const endpointUrl = new URL('https://api.spoonacular.com/recipes/complexSearch');
// Define API key here
const apiKey = '{{API_KEY}}';
// Define Header Parameters here
const headerParameters = {
  'x-api-key': apiKey,
  'content-type': 'application/json',
};
// Define Query Parameters here
const queryParameters = new URLSearchParams({
  query: 'Burger',
  cuisine: 'American',
  intolerances: 'dairy',
});
// Setting API call options
const endpointOptions = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function searchRecipes(url, options) {
  try {
    // Using the fetch method to make an API call to Spoonacular 
    const response = await fetch(url, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Attaching query parameters to the endpoint URL
endpointUrl.search = queryParameters;
// Calling function to make API call
searchRecipes(endpointUrl, endpointOptions);

Take a look at the following explanation of the code above:

  • Line 5: We use the endpoint URL /recipes/complexSearch to make a complex search of recipes.

  • Line 8: Here, we assign the API key to the apiKey variable.

  • Lines 11–14: We define the header parameters for the API call. We can modify or add parameters using the headerParameters variable.

    • Line 12: We pass the apiKey variable to the x-api-key header parameter.

  • Lines 17–21: We define the query parameters for the API call. We can modify or add parameters using the queryParameters variable.

    • Line 18: We fetch burger recipes using the query parameter to set the search query as Burger.

    • Line 19: We fetch recipes that are part of the American cuisine by filtering the search results using the cuisine parameter.

    • Line 20: We fetch recipes that do not contain any dairy by filtering the search results using the intolerances parameter.

The response of this endpoint is an array of recipe objects stored in the results field. Here are some of the fields from the API response:

Response Fields

Name

Type

Description

id

Number

The ID of the recipe

title

String

The title name of the recipe

image

String

The URL of the recipe’s image

imageType

String

The image type of the recipe's image

The search recipes nutrients endpoint

The search recipes nutrients endpoint searches for recipes according to nutrients. We can set nutritional limits for both macronutrients and micronutrients. The search recipes nutrients endpoint itself has a cost of 11quota point, while each recipe returned has a cost of 0.010.01quota point. The endpoint method and the URL are as follows:

GET https://api.spoonacular.com/recipes/findByNutrients

Here are some of the request parameters we can use with the search recipes nutrients endpoint when performing a recipe search:

Request Parameters

Parameter

Type

Category

Description

minCarbs

Number

Optional

The minimum number of carbohydrates that the recipes we’re fetching should have in grams.

maxCarbs

Number

Optional

The maximum number of carbohydrates that the recipes we’re fetching should have in grams.

minCalories

Number

Optional

The minimum number of calories that the recipes we’re fetching should have.

maxCalories

Number

Optional

The maximum number of calories that the recipes we’re fetching should have.

minProtein

Number

Optional

The minimum amount of protein that the recipes we’re fetching should have in grams.

maxProtein

Number

Optional

The maximum amount of protein that the recipes we’re fetching should have in grams.

minCholesterol

Number

Optional

The minimum amount of cholesterol that the recipes we’re fetching should have in milligrams.

maxCholesterol

Number

Optional

The maximum amount of cholesterol that the recipes we’re fetching should have in milligrams.

random

Boolean

Optional

The option, if set to true, randomizes recipe search results.

limitLicense

Boolean

Optional

The option, if set to true, ensures the API will only fetch recipes with an open license, allowing for proper attribution.

Note: For additional request parameters, refer to the "Additional Request Parameters" lesson.

Let’s see how to call the API endpoint to query recipes by nutrients. Click the “Run” button to execute the code.

Press + to interact
// Define endpoint URL here
const endpointUrl = new URL('https://api.spoonacular.com/recipes/findByNutrients');
// Define Query Parameters here
const queryParameters = new URLSearchParams({
  maxCarbs: 40,
  minCalories: 100,
  maxCalories: 400,
  maxCholesterol: 0,
  random: true,
  number: 5,
});
// Setting API call options
const endpointOptions = {
  method: 'GET',
  headers: headerParameters,
};
// Attaching query parameters to the endpoint URL
endpointUrl.search = queryParameters;
// Calling function to make API call
searchRecipesByNutrients(endpointUrl, endpointOptions);

Take a look at the following explanation of the code above:

  • Line 2: We use the endpoint URL /recipes/findByNutrients to search for recipes according to the nutritional limits in the dish.

  • Lines 5–12: We define the query parameters for the API call. We can modify or add parameters using the queryParameters variable.

    • Line 6: We fetch recipes with a maximum carbohydrate amount of 40 grams using the maxCarbs parameter.

    • Line 7: We fetch recipes with a minimum calorie amount of 100 using the minCalories parameter.

    • Line 8: We fetch recipes with a maximum calorie amount of 400 using the maxCalories parameter.

    • Line 9: We fetch recipes with a maximum cholesterol amount of 0 milligrams using the maxCholesterol parameter.

    • Line 10: We randomize the recipe search results by setting the random parameter to true, which means that the search results are random on every API call.

The response of this endpoint is an array of recipe objects. Here are some of the response fields of the API call we can get using its default behavior without enabling any additional request parameters:

Response Fields

Name

Type

Description

id

Number

The ID of the recipe

title

String

The title name of the recipe

image

String

The URL of the recipe’s image

imageType

String

The image type of the recipe’s image

calories

String

The number of calories in the recipe

protein

String

The amount of protein in the recipe in grams

fat

String

The amount of fat in the recipe in grams

carbs

String

The amount of carbs in the recipe in grams

cholesterol

String

The amount of cholesterol in the recipe in milligrams

The search recipes ingredients endpoint

The search recipes ingredients endpoint searches for recipes according to available ingredients. We can prioritize fetching either the recipes with the maximum usage of ingredients or recipes with the minimum number of unavailable ingredients. The search recipes ingredients endpoint itself has a cost of 11quota point, while each recipe returned has a cost of 11quota point. The endpoint method and URL are as follows:

GET https://api.spoonacular.com/recipes/findByIngredients
Press + to interact

Here are the request parameters we can use with the search recipes ingredients endpoint when performing a recipe search:

Request Parameters

Parameter

Type

Category

Description

ingredients

String

Optional

The ingredient(s) that the queried recipes should use. This parameter accepts a comma-separated list of ingredients.

ranking

Number

Optional

The option to either rank search results by most ingredients used if the set value is 1 or rank search results by the least unavailable ingredients if the set value is 2.

ignorePantry

Boolean

Optional

The option, if set to true, ensures the API will ignore any pantry ingredients such as flour, water, and salt in the ingredient search query.

number

Number

Optional

The number of results to include in the API response.

Possible values: 0–100.

limitLicense

Boolean

Optional

The option, if set to true, ensures the API will only fetch recipes with an open license, allowing for proper attribution.

Let’s see how to call the API endpoint to query recipes by ingredients. Click the “Run” button to execute the code.

Press + to interact
// Define endpoint URL here
const endpointUrl = new URL('https://api.spoonacular.com/recipes/findByIngredients');
// Define Query Parameters here
const queryParameters = new URLSearchParams({
  ingredients: 'milk,cream,egg,vanilla,strawberries,sugar',
  ranking: 2,
  ignorePantry: true,
  number: 5,
});
// Setting API call options
const endpointOptions = {
  method: 'GET',
  headers: headerParameters,
};
// Attaching query parameters to the endpoint URL
endpointUrl.search = queryParameters;
// Calling function to make API call
searchRecipesByIngredients(endpointUrl, endpointOptions);

Take a look at the following explanation of the code above:

  • Line 2: We use the endpoint URL /recipes/findByIngredients to search for recipes according to the dish's ingredients.

  • Lines 5–10: We define the query parameters for the API call. We can modify or add parameters using the queryParameters variable.

    • Line 6: We find recipes based on the ingredients we have assigned in the ingredients parameter. The ingredients we have assigned are the essential ingredients of a custard. Therefore, the search will be representative of that.

    • Line 7: We sort the recipe search results based on the minimum missing ingredients by setting the ranking parameter to 2.

    • Line 8: We instruct Spoonacular to ignore pantry items while searching for recipes by ingredients by setting the ignorePantry parameter to true.

The response of this endpoint is an array of recipe objects. Here are some of the response fields of the API call that we can get:

Response Fields

Name

Type

Description

id

Number

The ID of the recipe

title

String

The title name of the recipe

image

String

The URL of the recipe’s image

imageType

String

The image type of the recipe’s image

usedIngredientCount

Number

The number of ingredients used in the recipe

missedIngredientCount

Number

The number of ingredients missing from the recipe

missedIngredients

Object[ ]

An array of ingredient objects missing from the recipe

usedIngredients

Object[ ]

An array of ingredient objects used in the recipe

unusedIngredients

Object[ ]

An array of ingredient objects not used in the recipe