Food Database API Documentation

We have released the OpenAPI specification for the Food Database API!

We have released the OpenAPI specification for the Food Database API!

The Edamam B2B API is accessed by sending HTTPS requests on specific URLs as described below. The base URL is https://api.edamam.com, and you obtain the full URL by appending request’s path to the base URL, for example, https://api.edamam.com/api/food-database/v2/parser.

Our Food Database API allows you to search for nutrition and diet information within our Food Database.

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

 

The above OpenAPI specification for our API can be found here.
More information on OpenAPI can be found at: https://swagger.io/.

HTTP Compression

Edamam servers support standard HTTP compression using gzip. Using compression can reduce the size of the response and thus, increase the transfer speed.

The client can include the following header, to indicate what compression methods it supports:

Accept-Encoding: gzip

The server, then will include the following header to indicate the compressed response

Content-Encoding: gzip

or it will omit it, if the response is not compressed.

For more information see here: http://en.wikipedia.org/wiki/Http_compression

Nutrient Guide

The list of all of the nutrients that may be contained as part of a recipe’s nutritional information under the totalNutrients and the totalDaily section of the response. totalNutrients is the absolute nutrient amount, while totalDaily is the percent of daily recommended nutrient intake.

NTR Code Name Unit
SUGAR.added Added sugar g
CA Calcium, Ca mg
CHOCDF.net Carbohydrate (net) g
CHOCDF Carbohydrate, by difference g
CHOLE Cholesterol mg
ENERC_KCAL Energy kcal
FAMS Fatty acids, total monounsaturated g
FAPU Fatty acids, total polyunsaturated g
FASAT Fatty acids, total saturated g
FATRN Fatty acids, total trans g
FIBTG Fiber, total dietary g
FOLDFE Folate, DFE µg
FOLFD Folate, food µg
FOLAC Folic acid µg
FE Iron, Fe mg
MG Magnesium mg
NIA Niacin mg
P Phosphorus, P mg
K Potassium, K mg
PROCNT Protein g
RIBF Riboflavin mg
NA Sodium, Na mg
Sugar.alcohol Sugar alcohols g
SUGAR Sugars, total g
THIA Thiamin mg
FAT Total lipid (fat) g
VITA_RAE Vitamin A, RAE µg
VITB12 Vitamin B-12 µg
VITB6A Vitamin B-6 mg
VITC Vitamin C, total ascorbic acid mg
VITD Vitamin D (D2 + D3) µg
TOCPHA Vitamin E (alpha-tocopherol) mg
VITK1 Vitamin K (phylloquinone) µg
WATER Water g
ZN Zinc, Zn mg

Nutrient Structure

The structure of the Nutrients based on what is under the totalNutrients and totalDaily sections of the response.

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

Response Guide

Parsed

The “parsed” section of the response contains the top result for the food item in the query, its corresponding data (all the nutrients can be accessed via the “/nutrients” endpoint), as well as the measure and quantity of the query (if this has been included in the query).

I.e. Searching for “chicken”, you get the following:

  • The data for the food item “Chicken”

I.e. Searching for “1 whole chicken”, you get the following:

  • The data for the food item “Chicken”

  • The quantity as parsed from the query: “1”

  • The information for the measure “whole” and any qualifiers it might have

It is possible for a search to not have anything in the parsed section of the response if the query cannot be parsed.

Hints

The “hints” section of the response contains all the search results for the identified food item based on relevance. These will include all the corresponding data for the food items (all the nutrients can be accessed via the “/nutrients” endpoint), as well as all the measures (and their respective qualifiers) available for the item.

Pagination

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" : "https://api.edamam.com/api/food-database/v2/parser?..."
    }
}

Category

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

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

Measures

The 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
Ounce http://www.edamam.com/ontologies/edamam.owl#Measure_ounce
Gram http://www.edamam.com/ontologies/edamam.owl#Measure_gram
Pound http://www.edamam.com/ontologies/edamam.owl#Measure_pound
Kilogram http://www.edamam.com/ontologies/edamam.owl#Measure_kilogram
Pinch http://www.edamam.com/ontologies/edamam.owl#Measure_pinch
Liter http://www.edamam.com/ontologies/edamam.owl#Measure_liter
Fluid ounce http://www.edamam.com/ontologies/edamam.owl#Measure_fluid_ounce
Gallon http://www.edamam.com/ontologies/edamam.owl#Measure_gallon
Pint http://www.edamam.com/ontologies/edamam.owl#Measure_pint
Quart http://www.edamam.com/ontologies/edamam.owl#Measure_quart
Milliliter http://www.edamam.com/ontologies/edamam.owl#Measure_milliliter
Drop http://www.edamam.com/ontologies/edamam.owl#Measure_drop
Cup http://www.edamam.com/ontologies/edamam.owl#Measure_cup
Tablespoon http://www.edamam.com/ontologies/edamam.owl#Measure_tablespoon
Teaspoon http://www.edamam.com/ontologies/edamam.owl#Measure_teaspoon

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.

Ingredient Structure

The structure of the Ingredients based on what is under the ingredients section of the response.

Please note that some plans may not include all of the fields for the ingredient object.

Field Type Description
foodId string Food identifier
quantity float Quantity of specified measure
measure Measure Measure
weight float Total weight, g
food Food Food
foodCategory string Shopping aisle category

Diet Labels

The list of all possible Diet Labels generated from the nutrient information on the recipes. These labels describe commonly used nutrient level aspects of the recipe.

Type Web Label API Parameter Definition
Diet Balanced balanced Protein/Fat/Carb values in 15/35/50 ratio
Diet High-Fiber high-fiber More than 5g fiber per serving
Diet High-Protein high-protein More than 50% of total calories from proteins
Diet Low-Carb low-carb Less than 20% of total calories from carbs
Diet Low-Fat low-fat Less than 15% of total calories from fat
Diet Low-Sodium low-sodium Less than 140mg Na per serving

Health Labels

The list of all possible Health Labels generated from the ingredient information on the recipes. These labels describe commonly used ingredient level aspects of the recipe.

Type Web Label API Parameter Definition
Health Alcohol-free alcohol-free No alcohol used or contained
Health Immune-Supportive immuno-supportive Recipes which fit a science-based approach to eating to strengthen the immune system
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 Dietary Approaches to Stop Hypertension DASH
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 Keto keto-friendly Maximum 7 grams of net carbs per serving
Health Kidney friendly kidney-friendly Per serving – phosphorus less than 250 mg AND potassium less than 500 mg AND sodium less than 500 mg
Health Kosher kosher Contains only ingredients allowed by the kosher diet. However it does not guarantee kosher preparation of the ingredients themselves
Health Low potassium low-potassium Less than 150mg per serving
Health Lupine-free lupine-free Does not contain lupine or derivatives
Health Mediterranean Mediterranean
Health Mustard-free mustard-free Does not contain mustard or derivatives
Health Low-fat-abs low-fat-abs Less than 3g of fat per serving
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 Sugar-conscious sugar-conscious Less than 4g of sugar per serving
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

Meal Types

List of all possible Meal Types. The meal types refer to the meals in a day the recipe is commonly consumed in.

Type API Parameter
mealType Breakfast
mealType Lunch
mealType Dinner
mealType Snack
mealType Teatime

Dish Types

List of all possible Dish Types. The dish types refer to the category of food the recipe would fall under.

Type API Parameter
dishType Alcohol-cocktail
dishType Biscuits and cookies
dishType Bread
dishType Cereals
dishType Condiments and sauces
dishType Drinks
dishType Desserts
dishType Egg
dishType Main course
dishType Omelet
dishType Pancake
dishType Preps
dishType Preserve
dishType Salad
dishType Sandwiches
dishType Soup
dishType Starter

Cuisine Types

The list of all possible Cuisine Types. The cuisine types refer to the cuisine that the recipe would fall under.

Type API Parameter
cuisineType American
cuisineType Asian
cuisineType British
cuisineType Caribbean
cuisineType Central Europe
cuisineType Chinese
cuisineType Eastern Europe
cuisineType French
cuisineType Indian
cuisineType Italian
cuisineType Japanese
cuisineType Kosher
cuisineType Mediterranean
cuisineType Mexican
cuisineType Middle Eastern
cuisineType Nordic
cuisineType South American
cuisineType South East Asian