This API covers all key use cases related to recipe and food text natural language processing and nutrition analysis. The API employs NLP (Natural Language Processing) which allows for extraction of food entities from unstructured text.
Covered Use Cases
Path: https://api.edamam.com/api/nutrition-details
Returns nutritional information based on a POST
request of the recipe content
The following parameters are part of the POST
request URL:
Parameter | Required | Type | Description |
---|---|---|---|
app_id |
yes | string | Your 3scale application ID |
app_key |
yes | string | Your 3scale application key |
force |
no | Forces the re-evaluation of the recipe. The value, if any, is ignored. |
Recipe Analysis
RequestYou will use a POST request to submit the recipe content—more specifically the recipe title and ingredient list.
The response the API will return will contain nutritional analysis for the recipe based on the information provided.
The contents of the request must be a JSON object with the following format:
Name | Required | Description |
---|---|---|
title |
yes | common name of the recipe |
ingr |
yes | ingredients (array of strings) |
url |
no | url of the recipe’s location |
summary |
no | a short description of the recipe |
yield |
no* | number of servings |
ttime |
no | total time for preparation |
img |
no | image link (absolute) |
prep |
no | preparation instructions (free text) |
cuisine |
no | type of cuisine |
mealtype |
no | type of meal |
dishtype |
no | type of dish |
*While yield is not a required input if it is present it should make sense from a consumer perspective. Too high or too low weight per serving will affect the nutrition per serving and the recipe will not pass our automated quality check. If this happens the API will return a 555 error.
If not yield is specified Edamam will calculate the expected yield of the recipe.
The request must contain the header
Content-Type: application/json
Once you submit a recipe via the API you start paying Edamam a monthly licensing fee for each new analyzed recipe. Sometimes however, you may need to refresh the nutrition data for an already submitted recipe, in case you have lost the nutrition data for example. Submitting a recipe directly will count as analyzing a new recipe, and you will be charged again licensing fee for the nutrition information. To avoid that we’ve implemented a system based on HTTP’s ETag mechanism.
First, each successfully processed recipe will also return a tag in the ETag
response header. This value must be preserved together with the recipe. Then, when resubmitting the recipe, you should include the value in the If-None-Match
request header.
There three possible outcomes:
force
parameter. Edamam will know that you are already paying license for the nutrition information for this recipe, and you will not be charged twice.ETag
header. You should store that new value and use it for further resubmissions.ETag
hash contains a “signature” for the recipe content the system will respond with HTTP status code 409 – Conflict. In case you have used the wrong ETag
you can use correct the code, or if the recipe has changed you can resubmit the recipe as a new one (that is, without sending the If-None-Match
header).Licensing count example. You have analyzed 100 recipes in the first month, 50 the second month and 1 the third month. The first month you will pay a licensing fee for the nutrition of 100 recipes, the second month for 150 and the third for 151. If you don’t analyze any more recipes after the third month you will pay licensing fee for the nutrition for the total of 151 recipes every month thereafter.
POST
requestHere is an example using curl:
This will send the recipe.json
file for processing.
Here is the contents of the recipe.json
file:
HTTP Status code | Content-Type | Type | Description |
---|---|---|---|
200 OK | application/json | Recipe | Recipe object containing number of servings (yield), total calories for the recipe (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 recipe or extract the nutritional info |
555 | text/html | HTML | Recipe with insufficient quality to process correctly |
Here you can download a sample of the response with ingredient level nutrition data.
Note: Only a subset of the fields may be present, depending on the API plan through which the recipe data is obtained. Refer to the specific plan description for details.
Field | Type | Description |
---|---|---|
uri |
string | Ontology identifier |
yield |
integer | Number of servings |
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 |
---|---|---|
foodId |
string | Food identifier |
quantity |
float | Quantity of specified measure |
measure |
Measure | Measure |
weight |
float | Total weight, g |
food |
Food | Food |
Path: https://api.edamam.com/api/nutrition-data
Extracts information from a short unstructured food text – usually an ingredient line and returns:
- Structured data for the text – quantity, measure and food, if available
- Diet, health and allergen labels for the text
- With the build in food logging feature it allows for change of context. For example “rice” will normally be matched to raw rice while with the food logging feature on it will match to ready to eat ‘cooked rice’
Food Text Analysis
RequestYou will use a GET request to submit the ingredient.
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) |
nutrition-type |
no | string | When set to nutrition-type=logging it turns on the food logging feature |
ingr |
yes | string | The ingredient (don’t forget to URL-encode!) |
The API returns the nutritional analysis for the specified food text.
GET
requestAs an example, let’s say we want to extract information from the text ‘one large apple’. You should always include the quantity and the measure if you want to get nutrition for the line. Otherwise, you will get only a food match. We then need to URL-encode this string. In this case, this means to just replace the spaces with %20
, so it becomes “one%20large%20apple
”. Please note, that the quotation marks aren’t part of the string.
Also, it is important to note that the text breakdown to food, measure, quantity is available only for the plans where “Food and quantity extraction” feature is turned on. Please consult the API plan page for more details.
Here is an example using curl:
If you use the food logging context feature it will modify the NLP response in the following way
- You can submit items without quantity. We will try to match them and assign quantity to them based on expected serving size
- Only foods ready for direct consumption will be matched – no raw meats, raw dry goods or vegetables which need cooking 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
HTTP Status code | Content-Type | Type | Description |
---|---|---|---|
200 OK | application/json | Recipe | Recipe object containing number of servings (yield), total calories for the recipe (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 recipe or extract the nutritional info |
555 | text/html | HTML | Recipe with insufficient quality to process correctly |
Once you submit an ingredient line via the API you start paying Edamam a monthly licensing fee for each new analyzed ingredient line. Sometimes however, you may need to refresh the nutrition data for an already submitted ingredient line, in case you have lost the nutrition data for example. Submitting an ingredient line directly will count as analyzing a new ingredient line, and you will be charged again licensing fee for the nutrition information. To avoid that we’ve implemented a system based on HTTP’s ETag mechanism.
First, each successfully processed ingredient line will also return a tag in the ETag
response header. This value must be preserved together with the ingredient line. Then, when resubmitting the ingredient line, you should include the value in the If-None-Match
request header.
There three possible outcomes:
force
parameter. Edamam will know that you are already paying license for the nutrition information for this ingredient line, and you will not be charged twice.ETag
header. You should store that new value and use it for further resubmissions.ETag
hash contains a “signature” for the text content the system will respond with HTTP status code 409 – Conflict. In case you used the wrong ETag
you can use correct the code, or if the text/ingredient line has changed you can resubmit the ingredient line as a new one (that is, without sending the If-None-Match
header).Licensing count example. You have analyzed 1000 ingredient lines in the first month, 500 the second month and 10 the third month. The first month you will pay licensing fee for the nutrition of 1000 ingredient line, the second month for 1500 and the third for 1510. If you don’t analyze any more ingredient line after the third month you will pay licensing fee for the nutrition for the total of 1510 ingredient line every month thereafter.
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 |
SUGAR | Sugars | g | SUGAR.added | Sugars, added | g |
FAT | Fat | g | FASAT | Saturated | g |
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 | FOLFD | Folate (food) | æg |
K | Potassium | mg | VITC | Vitamin C | mg |
MG | Magnesium | mg | VITD | Vitamin D | æg |
NA | Sodium | mg | VITK1 | Vitamin K | æg |
VITB6A | Vitamin B6 | mg | THIA | Thiamin (B1) | mg |
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 |
---|---|---|---|
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 |
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 |
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 |
Mustard-free | mustard-free | Does not contain mustard or derivatives |
Health |
n/a | 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 |
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.