Food Database API Documentation
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/.
Edamam Platform Assistant
The Edamam Platform Assistant is a chatbot integrated into four of Edamam’s API. This can provide an easy to use intuitive interface for your customers. The assistant allows you to submit natural language queries and receive back the necessary API calls needed in order to obtain the data requested by your query.
The Food Database API is integrated into this service, allowing the Edamam Platform Assistant to construct requests using all the parameters seen above. The Edamam Platform Assistant Documentation can be found here.
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
Active User Tracking
In order to have Active User tracking, your app_id should be configured with this feature. If the app_id has been configured with this feature, the header for the user ID becomes mandatory or else an error will occur. If your app_id has not been set up for this feature, requests with it will result in error. Contact us if this is a feature you require.
There are restrictions on valid characters for user_ids. Allowed characters are: a-z/A-Z, 0-9, “-”, “_”, “.”. With a maximum length of 30 characters.
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.
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 |