Food Database API Documentation

This is documentation for Version 2 of the Food Database API. If you need to see what are the changes from Version 1 please go to the changelog

Food Database

This API provides you with tools to find nutrition and diet data for generic foods, packaged foods and restaurant meals. In addition, it employs NLP (Natural Language Processing) which allows for extraction of food entities from unstructured text.

Covered Use Cases

  • Search for food by keyword, food name or UPC/Barcode
  • Sourcing of nutrition facts for a given food, including: macro and micro nutrients, allergen labels, lifestyle and health labels
  • Search for food by given nutrient quantity for 28 nutrients
  • Search for foods within a given brand
  • With the built-in food-logging context it allows for NLP requests for chatbots and natural language calorie counters

Food Database Requests

Parse requests:

Food Database Text Search

The parser access point handles text search for foods as well as filters for the foods like presence specific nutrient content or exclusion of allergens

  • Search for a phrase or keyword using NLP to get food entities from it.
  • Get basic nutrition facts and ingredients for each food
  • Search for food by given nutrient quantity for 28 nutrients
  • Search for foods within a given brand
  • With the build in food-logging context it allows for requests which do not contain quantity and suggest expected quantities for them.

Parser Request

You will use a GET request to access the Parser. Either UPC or ingr should be present for a valid request

When searching by keyword

Parameter Required Type Description
app_id yes string Your 3scale application ID
app_key yes string Your 3scale application key (please note app_id/app_key are an ordered pair)
ingr yes * string A keyword search parameter to be found in the food name. *Not required when upc is present
upc yes * string A valid UPC code. *Not required when ingr is present
nutrition-type no string When set to nutrition-type=logging it turns on the food logging feature
health no enum Health label: One of the Health API parameters listed in Diet and Health Labels table at the end of this documentation. For example “peanut-free”, “tree-nut-free”, “soy-free”, “fish-free”, “shellfish-free”
calories no Range The format is calories=RANGE where RANGE is replaced by the value in kcal. RANGE is in one of MIN+, MIN-MAX or MAX, where MIN and MAX are non-negative integer numbers. The + symbol needs to be properly encoded. Examples: “calories=100-300” will return all foods with which have between 100 and 300 kcal per serving.
page no integer Deprecated parameter, see Pagination section instead. Support for this parameter will soon be removed. The page parameter lists results from the selected page (20 per page). The first page is page “0”.
category no string Category as- generic-foods, generic-meals, packaged-foods, fast-foods
categoryLabel no string Item type as – food or meal. Food is usually basic component of meal

When using food logging context

If you use the food logging context feature it will modify the NLP response in the following ways
- You can submit items without quantity. Edamam will try to match them and assign quantity to them based on expected serving size
- The API will return as results only foods ready for direct consumption – no raw meats, raw dry goods, like raw rice for example
- Edamam can handle single items and two part compound items only – i.e. “chicken” or “rice AND chicken”. Make sure the URL is encoded properly


To obtain the next page, the API user should follow the “next” link from the “_links” section in the result JSON, which looks like this:

"_links" : {
    "next" : {
      "title" : "Next page",
      "href" : ""

Search by nutrient range

When searching by keyword you can also specify nutrient ranges by adding parameters in the following form:

nutrients[NTR]=RANGE where



RANGE is in one of MIN+, MIN-MAX or MAX, where MIN and MAX are non-negative integer numbers.

For example:
nutrients[CA]=50+ means minimum 50 mg calcium, where ‘50+’ has to be properly encoded as ‘50%2B’
nutrients[FAT]=30 means maximum 30 g fat and
nutrients[FE]=5-10 means iron between 5 mg and 10 mg inclusive

You can combine more than one nutrient ranges in a search requests

NTR Code Name Unit NTR Code Name Unit
CA Calcium mg ENERC_KCAL Energy kcal
CHOCDF Carbs g NIA Niacin (B3) mg
CHOLE Cholesterol mg P Phosphorus mg
FAMS Monounsaturated g PROCNT Protein g
FAPU Polyunsaturated g RIBF Riboflavin (B2) mg
FASAT Saturated g SUGAR Sugars g
FAT Fat g THIA Thiamin (B1) mg
FATRN Trans g TOCPHA Vitamin E mg
FE Iron mg VITA_RAE Vitamin A æg
FIBTG Fiber g VITB12 Vitamin B12 æg
FOLDFE Folate (Equivalent) æg VITB6A Vitamin B6 mg
K Potassium mg VITC Vitamin C mg
MG Magnesium mg VITD Vitamin D æg
NA Sodium mg VITK1 Vitamin K æg

Category and CategoryLabel Parameters

Category is a parameter that can be used when making a request in order to narrow down the results. They will narrow the results according to the following:

Category Description
generic-foods Any general non-branded food i.e. searching “apple” with this category returns information on generic “apple” and its varieties.
packaged-foods Any food that has been produced as a Consumer Packaged Good (CPG,) i.e. one of the results when searching “apple” returns an “Apple” packaged and branded from “Apple Country”
generic-meals Any generic (non-branded) food that is composed of other basic foods, these will usually come with a list of ingredients. i.e. searching “apple” returns “Apple-Crisp Baked Apples”
fast-foods Any food that is served by a chain-restaurant. i.e. searching “apple” returns “Apples” which are served by “bareburger”

CategoryLabel is another parameter that can be used to narrow down search results based on a broader criteria than Category. The following can be used for this parameter:

CategoryLabel Description
food Refers to basic foods or food products (i.e. not composed of other foods,) equivalent of searching in both generic-foods and packaged-foods
meal Refers to foods that are composed of basic foods, equivalent of searching in both generic-meals and fast-foods

Example Parser request

As an example, let’s say we want to find matches in the food database for a red apple. We then need to URL-encode this string. In this case, this means to just replace the spaces with %20,so it becomes “red%20apple” Please note, that the quotation marks aren’t part of the string.
Here is an example using curl:

'{your app_id}&app_key={your app_key}'

NOTE: Please make sure you use the credentials you created for this exact API as they are app and plan specific. The ${ } notation is to signify the type of input and should NOT to be included in the request itself.

With ‘food-logging’ turned on:

'{your app_id}&app_key={your app_key}'

Parser Response

HTTP Status code Description
200 OK List of food objects, with each food object containing: kcal per 100 grams, protein per 100 grams, carbohydrates per 100 grams, brand of the food, if the food is generic or branded, a list of existing measures for the food, contents label of the food
404 Not Found The specified URL was not found or couldn’t be retrieved


Field Type Description
foodId string Unique food identifier
label string Display label
measure Measure Contains measure URI and display label
nutrients Nutrients Quantity of kcal, protein, fat, carbs if >0

NOTE: The ‘parsed’ section of the response contains the direct result from NLP handling of the request with it broken down into quantity/measure/food. This data then is used to produce the results from the ‘hints’ section.


Field Type Description
foodId string Unique food identifier
label string Display label
measure Measure Contains a list of available specific food measure URIs and display labels
nutrients Nutrients Quantity of kcal, protein, fat, carbs if >0
brand string For example brand ‘Burger King’ for the item ‘hamburger’
category string Category as: Generic foods (non-branded basic ingredients), Generic meals (non-branded generic meals), Packaged foods (items with barcode), Fast foods (chain restaurant items)
categoryLabel string Item type as food or meal. Food is usually a basic component of the meal
image string Contains URL to an image of the food when available
servingSizes Measure Contains serving size information for packaged foods as listed on the packaging label

Example response to text search

*Nutrition Data Requests

Nutrition Requests:

In the response to your parser request you receive the a food ID for each database match. Using the food ID and the measure URI which parser provides you can make a request to the nutrients access point. The nutrients access points returns nutrition with diet and health labels for a given quantity of the food.

Nutrients Request

The contents of the request must be a JSON object with the following format:

Parameter Required Type Description
ingredients yes Ingredient[] Ingredient (array of one ingredient)


Parameter Required Type Description
quantity yes number The quantity of the ingredient
measureURI yes string One of the measurement URI’s received in the parser response
foodId yes string The food ID received in the parser response

The Parser response for each food contains all specialized measures for this food. For example if an apple has a specific unit named ‘slice’ it will come with the response from the API.

In addition to the units provided by the API Edamam supports virtually any weight and volume measures for all foods. Edamam does not return them in the API as it makes the response redundant and cumbersome.

Here is a list of the standard supported measures which can be used in addition the measures returned with the food:

Name URI
Fluid ounce

A given measure may or may not contain a field “qualified”. This field contains possible measure qualifiers for the basic measure with each of them having its own URI. For example for the item ‘apple’ one of the measures is ‘whole’ with qualifiers ‘large’, ‘small’ etc.

When submitted together with the measure URI the qualifier URI changes the weight of the basic measure.

The API returns nutritional analysis for the specified ingredient.

Each food comes with a list of specialized units which belong to it. For example if an apple has a specific unit named slice it will come with the response from the API.

Example Nutrients request

You will use a POST request to access ‘nutrients’.

Here is an example using curl:

This will send the food.json file for processing.

Here are the contents of the food.json file:

  "ingredients": [
      "quantity": 1,
      "measureURI": "",
      "foodId": "food_bnbh4ycaqj9as0a9z7h9xb2wmgat"

When a qualifier is available for a given measure it can be used in the following way:

  "ingredients": [
      "quantity": 1,
      "measureURI": "",
      "foodId": "food_bnbh4ycaqj9as0a9z7h9xb2wmgat",
      "qualifiers": [ "" ]

Nutrients Response

HTTP Status code Content-Type Type Description
200 OK application/json FoodInfo Object containing number of servings (yield), total calories for the food (calories), nutrient content by nutrient type (totalNutrients, totalDaily), diet and health classification (dietLabels, healthLabels)
404 Not Found text/html HTML The specified URL was not found or couldn’t be retrieved
422 Unprocessable Entity text/html HTML Couldn’t parse the request or extract the nutritional info
555 text/html HTML Text with insufficient quality to process correctly

Example Nutrients response


Field Type Description
uri string Ontology identifier
calories float Total energy, kcal
totalNutrients NutrientInfo[*] Total nutrients
totalDaily NutrientInfo[*] % daily value
dietLabels enum[] Diet labels: “balanced”, “high-protein”, “high-fiber”, “low-fat”, “low-carb”, “low-sodium”
healthLabels enum[] Health labels: “vegan”, “vegetarian”, “dairy-free”, “low-sugar”, “low-fat-abs”, “sugar-conscious”, “fat free”, “gluten free”, “wheat free”

For ‘Nutritional Label Definitions’ consult the table at the bottom of this document


Field Type Description
uri string Ontology identifier
label string Display label
quantity float Quantity of specified units
unit string Units


Field Type Description
uri string Ontology identifier
quantity float Quantity of specified measure
measure Measure Measure
weight float Total weight, g
food Food Food

UPC or Barcode Search

Allows for search of an item based UPC/Barcode number.

This is a service allowing you to submit a UPC or barcode and find a match for it in the food database.

Parameter Required Type Description
app_id yes string Your 3scale application ID
app_key yes string Your 3scale application key (please note app_id/app_key are an ordered pair)
upc yes Number The UPC or barcode number for the food

Here is an example using curl:
'{upc code}&app_id={your app_id}&app_key={your app_key}'

Autocomplete Request

Edamam provides a convinient autocomplete functionality which can be used when searching for ingredients.


The endpoint returns suggestions for the text submitted to it. Here is an example${YOUR_APP_ID}&app_key=${YOUR_APP_KEY}

Nutritional Label Definitions

Nutrition labels are shared by recipes and foods alike. They are assigned by Edamam based on the ingredients contained in the food label for CPG foods and by the basic ingredients of each recipe for recipes.

Type Web Label API Parameter Definition
Health Alcohol-free alcohol-free No alcohol used or contained
Health Celery-free celery-free does not contain celery or derivatives
Health Crustcean-free crustacean-free does not contain crustaceans (shrimp, lobster etc.) or derivatives
Health Dairy dairy-free No dairy; no lactose
Health Eggs egg-free No eggs or products containing eggs
Health Fish fish-free No fish or fish derivatives
Health FODMAP free fodmap-free Does not contain FODMAP foods
Health Gluten gluten-free No ingredients containing gluten
Health Kosher kosher contains only ingredients allowed by the kosher diet. However it does not guarantee kosher preparation of the ingredients themselves
Health Lupine-free lupine-free does not contain lupine or derivatives
Health Mustard-free mustard-free does not contain mustard or derivatives
Health No oil added No-oil-added No oil added except to what is contained in the basic ingredients
Health No-sugar low-sugar No simple sugars – glucose, dextrose, galactose, fructose, sucrose, lactose, maltose
Health Paleo paleo Excludes what are perceived to be agricultural products; grains, legumes, dairy products, potatoes, refined salt, refined sugar, and processed oils
Health Peanuts peanut-free No peanuts or products containing peanuts
Health Pescatarian pecatarian Does not contain meat or meat based products, can contain dairy and fish
Health Pork-free pork-free does not contain pork or derivatives
Health Red meat-free red-meat-free does not contain beef, lamb, pork, duck, goose, game, horse, and other types of red meat or products containing red meat.
Health Sesame-free sesame-free does not contain sesame seed or derivatives
Health Shellfish shellfish-free No shellfish or shellfish derivatives
Health Soy soy-free No soy or products containing soy
Health Tree Nuts tree-nut-free No tree nuts or products containing tree nuts
Health Vegan vegan No meat, poultry, fish, dairy, eggs or honey
Health Vegetarian vegetarian No meat, poultry, or fish
Health Wheat-free wheat-free No wheat, can have gluten though


Composite types are described in terms of their JSON representation.

Throughout descriptions, the following notation is used:

  • integer, float, and string stand for the JavaScript primitive types integer, float, and string, respectively
  • enum stands for a string field that only takes on values from a pre-defined range (the range is specified where essential)
  • T[] stands for an array of objects of type T
  • T[\* stands for an object (associative map) whose every field (element) is of type T.