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
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
Parse requests: https://api.edamam.com/api/food-database/v2/parser
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
Parser
RequestYou will use a GET request to access the Parser. Either UPC
or ingr
should be present for a valid request
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 |
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" : "https://api.edamam.com/api/food-database/v2/parser?..."
}
}
When searching by keyword you can also specify nutrient ranges by adding parameters in the following form:
nutrients[NTR]=RANGE where
NTR is one of: CA, CHOCDF, CHOLE, FAMS, FAPU, FASAT, FAT, FATRN, FE, FIBTG, FOLDFE, K, MG, NA, NIA, P, PROCNT, RIBF, SUGAR, THIA, TOCPHA, VITA_RAE, VITB12, VITB6A, VITC, VITD, VITK1 or ZN;
and
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 |
Parser
requestAs 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:
'https://api.edamam.com/api/food-database/v2/parser?ingr=red%20apple&app_id={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:
'https://api.edamam.com/api/food-database/v2/parser?nutrition-type=logging&ingr=red%20apple&app_id={your app_id}&app_key={your app_key}'
Parser
ResponseHTTP 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 |
Nutrition Requests: https://api.edamam.com/api/food-database/v2/nutrients
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
RequestThe 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 |
---|---|
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.
Nutrients
requestYou 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": "http://www.edamam.com/ontologies/edamam.owl#Measure_unit",
"foodId": "food_bnbh4ycaqj9as0a9z7h9xb2wmgat"
}
]
}
When a qualifier is available for a given measure it can be used in the following way:
{
"ingredients": [
{
"quantity": 1,
"measureURI": "http://www.edamam.com/ontologies/edamam.owl#Measure_unit",
"foodId": "food_bnbh4ycaqj9as0a9z7h9xb2wmgat",
"qualifiers": [ "http://www.edamam.com/ontologies/edamam.owl#Qualifier_large" ]
}
]
}
Nutrients
ResponseHTTP 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 |
Nutrients
responseField | 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 |
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:
'https://api.edamam.com/api/food-database/v2/parser?upc={upc code}&app_id={your app_id}&app_key={your app_key}'
Edamam provides a convinient autocomplete functionality which can be used when searching for ingredients.
Path: http://api.edamam.com/auto-complete
The endpoint returns suggestions for the text submitted to it. Here is an example
http://api.edamam.com/auto-complete?q=rou&limit=10&app_id=${YOUR_APP_ID}&app_key=${YOUR_APP_KEY}
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:
T[*]
stands for an object (associative map) whose every field (element) is of type T.