Search Grocery Products

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

We'll cover the following

We can use the Spoonacular API to search for grocery products either by a search query or nutrients. To do so, we can use the following endpoints based on our use case:

  • search products by query string
  • search products by UPC
  • search products by ingredients

The search products by query string endpoint

The search products by query string endpoint performs a product search for a given query of packaged food products. The search products by query string endpoint has a cost of 11quota point, while each product returned has a cost of 0.010.01quota point. If the addProductInformation parameter is set to true, each product will have a cost of 11quota point. This endpoint utilizes the GET method and uses the following URL:

GET https://api.spoonacular.com/food/products/search

Here are some of the request parameters we can use with the search products by query string endpoint:

Request Parameters

Parameter

Type

Category

Description

query

String

Optional

The search query to look up the ingredient.

minCalories

Number

Optional

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

maxCalories

Number

Optional

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

minCarbs

Number

Optional

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

maxCarbs

Number

Optional

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

minProtein

Number

Optional

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

maxProtein

Number

Optional

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

minFat

Number

Optional

The maximum amount of fat that the products we’re fetching should have in grams.

maxFat

Number

Optional

The maximum amount of fat that the products we’re fetching should have in grams.

addProductInformation

Boolean

Optional

The option, if set to true, ensures the API will add detailed information about each product in the search result.

Let’s see how to call the API endpoint. 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/food/products/search');
// 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: 'chocolate',
  maxCalories: 500,
  minProtein: 10,
  number: 10,
});
// Setting API call options
const endpointOptions = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function searchProductsByQuery(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
searchProductsByQuery(endpointUrl, endpointOptions);

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

  • Line 5: We use the endpoint URL /food/products/search to search for grocery products using a search query.

  • Line 8: We assign the API key here 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–22: We define the query parameters for the API call. We can modify or add parameters using the queryParameters variable.

    • Line 18: We fetch chocolate-related products using the query parameter to set the search query as chocolate.

    • Line 19: We fetch products with a maximum calorie amount of 500 using the maxCalories parameter.

    • Line 20: We fetch products with a minimum protein amount of 10 using the minProtein parameter.

The response of this endpoint contains an array of product objects stored in the products field. Here are some of the fields from the API response:

Response Fields

Name

Type

Description

id

Number

The ID of the product

title

String

The title name of the product

image

String

The URL of the product’s image

imageType

String

The image type of product's image

The search products by UPC endpoint takes in the Universal Product Code (UPC) of a product as a path parameter and fetches detailed information for that product.

The UPC is something that can we can find printed on retail products to identify them. It is a combination of machine-readable bar codes and 12-digit number code that contains information like brand name, item name, color, and size.

The search products by UPC endpoint has a cost of 11 quota point. The endpoint method and URL are as follows:

GET https://api.spoonacular.com/food/products/upc/{upc}

We can use one of the following product UPCs for the code widget in this section:

Product UPCs

Product Name

UPC

Hershey’s Milk Chocolate Bar

034000232581

Kellogg's Froot Loops

643952402227

Swan Flour

041631000564

Doritos Chips

028400420730

Here is the request parameter we can use with the search products by UPC endpoint:

Request Parameters

Parameter

Type

Category

Description

upc

Number

Required

The UPC of the product for which we’re fetching the detailed information.

Let’s see how to call the API endpoint. Click the “Run” button to execute the code. Make sure you’ve provided the value for PRODUCT_UPC.

Press + to interact
// Define the UPC of any product here
const upc = '{{PRODUCT_UPC}}';
// Define endpoint URL here
const endpointUrl = new URL(`https://api.spoonacular.com/food/products/upc/${upc}`);
// Setting API call options
const endpointOptions = {
  method: 'GET',
  headers: headerParameters,
};
// Calling function to make API call
searchProductsByUPC(endpointUrl, endpointOptions);

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

  • Line 2: We set and store the UPC of a product that we want to use to fetch the product.

  • Line 5: We use the endpoint URL /food/products/upc/{upc} to fetch detailed information about the product using its UPC.

Here are some of the fields from the API response:

Response Fields

Name

Type

Description

id

Number

The ID of the product

title

String

The title name of the product

price

Number

The price of the product

badges

String[ ]

The list of diets and intolerances associated with the product

nutrition

Object[ ]

A list of nutrition objects related to the product

ingredients

Object[ ]

A list of ingredient objects related to the product

brand

String

The brand of the product

The search products by ingredients endpoint

The search products by ingredients endpoint takes in a list of ingredients and servings as body parameters and maps them to grocery store products. The search products by ingredients endpoint has a cost of 11quota point per product. The endpoint method and URL are as follows:

POST https://api.spoonacular.com/food/ingredients/map

Here are some of the request body parameters we can use with the search products by ingredients endpoint:

Request Parameters

Parameter

Type

Category

Description

ingredients

String[ ]

Required

The list of ingredients for which we want to map grocery products. We need to pass this parameter in the request body rather than as a query or path parameter.

servings

Number

Required

The number of people that the product can serve. We need to pass this parameter in the request body rather than as a query or path parameter.

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

Press + to interact
// Define endpoint URL here
const endpointUrl = new URL('https://api.spoonacular.com/food/ingredients/map');
// Define Body Parameters here
const bodyParameters = JSON.stringify({
  'ingredients': [
    'eggs',
    'bread',
    'milk',
  ], 
  'servings': 2,
});
// Setting API call options
const endpointOptions = {
  method: 'POST',
  headers: headerParameters,
  body: bodyParameters,
};
// Calling function to make API call
searchProductsByIngredients(endpointUrl, endpointOptions);

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

  • Line 2: We use the endpoint URL /food/ingredients/map to search for grocery products using a list of ingredients.

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

The response of this endpoint contains an array of queried ingredients in which we can find the array of product objects in the products field. Here are some of the fields from the API response:

Response Fields

Name

Type

Description

originalName

String

The name of the ingredient used in the search query

products

Object[ ]

The list of product objects associated with the ingredient

id

Number

The ID of the product

upc

String

The UPC of the product

title

String

The title name of the product